TriSpectorP API - TriSpectorP 4.2.0.214R

Image.multiplyAddConstantInplace

Parameters
Name	Type	Description
filepath	STRING	The path and name of the file to load the image from.

Return values
Name	Type	Description
image	OBJECT Image	The Image object which is loaded.

Sample

local image = Image.load("resources/image.bmp")

max()

Short description

Creates an image with the maximum pixel values of the source images. The images must be of equal size and pixel type. Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. The operation is interpreted as operating on the world z-coordinate values. The input images are allowed to have different image world coordinate systems, but only the z-pixelsizes and z-origins are utilized, pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation. Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image.

Keywords

arithmetic, compare, maximum

Parameters
Name	Type	Description
image1	CONST_OBJECT Image	The first source image.
image2	CONST_OBJECT Image	The second source image.

Return values
Name	Type	Description
result	OBJECT Image	The maximum image.

Sample

result = Image.max(image1, image2)

maxInplace()

Short description

Inplace version of the Image.max function which modifies the first input image to contain the pixelwise maximum of the input images. See base function for full documentation.

Keywords

arithmetic, compare, maximum

Parameters
Name	Type	Description
image1	OBJECT Image	The first source image. This image is overwritten with the pixelwise maximum.
image2	CONST_OBJECT Image	The second source image.

Return values
Name	Type	Description
result	OBJECT Image	Reference to the result image.

Sample

result = Image.maxInplace(image1, image2)

median()

Short description

Applies median filter to the image to smooth and remove noise. Image world coordinate system handling: The median filter kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image. Missing data handling: For an image with the missing data flag set, the filtering will ignore the missing data pixels in the filtering operation so that they do not influence the result. Note that it is computationally more expensive to filter a missing data image though. While filtering, there is an option to fill in missing data pixels locally if possible. The amount filled in depends on the kernel size. If this option is not used, an missing data input pixel will generate a missing data output pixel. The output image inherits the missing data flag of the input image.

Keywords

denoise, edge preserving, filter, smooth

Parameters
Name	Type	Description
image	CONST_OBJECT Image	Input image. Supported image types are uint8, uint16, int16 and float32.
kernelSizePix	INT	Size of the kernel, must be positive and odd. For kernel sizes larger than 5 the only supported image type is uint8.
region	CONST_OBJECT Image.PixelRegion	Optional region of interest. Enter the value nil to filter the entire image. If a non-empty region is supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Output pixel values outside the region are undefined.
fillMissingData	BOOL	Optional flag to also fill in missing data pixels when smoothing images containing missing data. Default is false.

Return values
Name	Type	Description
medianImage	OBJECT Image	Output image blurred by the median filter.

Sample

medianImage = Image.median(image, kernelSizePix)

min()

Short description

Creates an image with the minimum pixel values of the source images. The images must be of equal size and pixel type. Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. The operation is interpreted as operating on the world z-coordinate values. The input images are allowed to have different image world coordinate systems, but only the z-pixelsizes and z-origins are utilized, pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation. Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image.

Keywords

arithmetic, compare, minimum

Parameters
Name	Type	Description
image1	CONST_OBJECT Image	The first source image.
image2	CONST_OBJECT Image	The second source image.

Return values
Name	Type	Description
result	OBJECT Image	The minimum image.

Sample

result = Image.min(image1, image2)

minInplace()

Short description

Inplace version of the Image.min function which modifies the first input image to contain the pixelwise minimum of the input images. See base function for full documentation.

Keywords

arithmetic, compare, minimum

Parameters
Name	Type	Description
image1	OBJECT Image	The first source image. This image is overwritten with the pixelwise minimum.
image2	CONST_OBJECT Image	The second source image.

Return values
Name	Type	Description
result	OBJECT Image	Reference to the result image.

Sample

result = Image.minInplace(image1, image2)

mirror()

Short description

Mirrors an image in the horizontal or vertical axis. Image world coordinate system handling: The image world coordinate system is copied from the input image, only the image content is mirrored. Missing data handling: All missing data values will be retained after mirroring.

Keywords

flip

Parameters
Name	Type	Description
image	CONST_OBJECT Image	Input image.
mirrorHorizontally	BOOL	Set to true to mirror horizontally in the vertical axis, set to false to mirror vertically in the horizontal axis.

Return values
Name	Type	Description
mirroredImage	OBJECT Image	The mirrored image

Sample

mirroredImage = Image.mirror(image, mirrorHorizontally)

missingDataReduce()

Short description

Reduces missing data pixels in an image by using valid values in the neighborhood. Valid pixel values are unaffected. This will fill in scattered missing data values but larger patches of missing data will remain. The type of operation performed to fill a missing pixel is selected using the method parameter. Optionally, reduction of missing data can be limited to a region in the image. Valid pixel values within a neighborhood but outside the region will still be used to fill missing data. To fill a missing pixel, at least one quarter of the neighbor pixels need to have valid values. The available methods are: MAX - Sets missing pixels to the maximum valid value in the neighborhood. MIN - Sets missing pixels to the minimum valid value in the neighborhood. MEAN - Sets missing pixels to the mean of all valid values in the neighborhood. MEDIAN - Sets missing pixels to the median of all valid values in the neighborhood. EDGE - Fills missing values by edge-preserving interpolation among pixels in the 3x3 pixel neighborhood. A missing data pixel will be filled in only if there are valid values on both sides of a pixel. For all methods except EDGE, the neighborhood is nSize-by-nSize pixels. nSize must be odd and at least three. For method EDGE, nSize determines how many times the algorithm will be repeated. For EDGE, nSize must be a positive integer.

Parameters
Name	Type	Description
inputImage	CONST_OBJECT Image	The input image. An error is returned if the input image does not have the missing data flag set.
method	ENUM MissingDataMethod	Method to be used for reducing missing data.
nSize	INT	The size of the neighborhood for most methods, the number of iterations for EDGE. Default is 3.
region	CONST_OBJECT Image.PixelRegion	Optional region of interest. If supplied, the filter operation is only performed within this region. This can save a lot of computation time, if the region is small.

Return values
Name	Type	Description
outputImage	OBJECT Image	The output image, or nil if an error occurred.

Sample

outputImage = Image.missingDataReduce(inputImage, method, nSize, region)

missingDataSetAll()

Short description

Sets all missing data pixels in the entire image or within a specified region to a given value. All missing pixels are set and the missing data flag of the image is cleared. If a region is provided, only pixels within the region are considered. The missing data flag of the image is still cleared, leaving any pixels with missing data outside the region in an undetermined state. Image world coordinate system handling: The specified value parameter is interpreted in image world coordinates, e.g., in millimeters if the source image is a range image with a z-origin different than 0 and a z-pixelsize different than 1. The output image inherits the image world coordinate system of the input image. Missing data handling: The missing data flag is removed from the output image, also if the operation is only performed within a region of interest.

Parameters
Name	Type	Description
image	CONST_OBJECT Image	The input image.
valueWorld	FLOAT	The value to set, in world coordinates considering z-origin and z-pixelsize if applicable.
region	CONST_OBJECT Image.PixelRegion	A region of interest to operate within. Optional, default is operate on the entire image.

Return values
Name	Type	Description
result	OBJECT Image	The output image.

Sample

result = Image.missingDataSetAll(image, value, region)

missingDataSetAllInplace()

Short description

Inplace version of the Image.missingDataSetAll function that modifies the input image. See base function for full documentation.

See also

Image.missingDataSetAll

Parameters
Name	Type	Description
image	OBJECT Image	The image to set missing data in. This image is overwritten with the result image.
valueWorld	FLOAT	The value to set, in world coordinates considering z-origin and z-pixelsize if applicable.
region	CONST_OBJECT Image.PixelRegion	A region of interest to operate within. Optional, default is operate on the entire image.

Return values
Name	Type	Description
result	OBJECT Image	Reference to the result image.

Sample

result = Image.missingDataSetAllInplace(image, value, region)

missingDataSetSurface()

Short description

Sets all missing data pixels to the surface value, values are clamped to the representable range of the image. All valid values are left unchanged. If a region not covering the full image is used, any missing data outside the region will be left in an undetermined state. Currently, only a plane surface represented as a Shape3D is supported, other surface types may be supported in the future. Image world coordinate system handling: The surface is interpreted in world space which is compared with image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the input image is copied to the output image. Missing data handling: This function replaces all missing data pixels with the surface value. The missing data flag for the output image is removed, also when this operation is performed only within a specified region of interest.

Parameters
Name	Type	Description
image	CONST_OBJECT Image	The image to set missing data in.
surface	CONST_OBJECT Shape3D	The surface to clamp to, represented as a Shape3D. Currently only a plane type is supported, in future more surface types may be supported.
region	CONST_OBJECT Image.PixelRegion	Optional region where the operation is to be performed, default is the full image.

Return values
Name	Type	Description
clampedImage	OBJECT Image	The image without missing data. Nil if an error occurred.

Sample

clampedImage = Image.missingDataSetSurface(image, surface, region)

missingDataSetSurfaceInplace()

Short description

Inplace version of the Image.missingDataSetSurface function which modifies the input image by adding the value of a given plane. See base function for full documentation.

Parameters
Name	Type	Description
image	OBJECT Image	The image to set missing data in. This image is overwritten and the missing data is set according to the surface value.
surface	CONST_OBJECT Shape3D	The surface to clamp to, represented as a Shape3D. Currently only a plane type is supported, in future more surface types may be supported.
region	CONST_OBJECT Image.PixelRegion	Optional region where the operation is to be performed, default is the full image.

Return values
Name	Type	Description
result	OBJECT Image	Reference to the result image.

Sample

result = Image.missingDataSetSurfaceInplace(image, surface, region)

morphology()

Short description

A morphological transformation applied to grayscale images. The possible transformation types are: ERODE, DILATE, OPEN, CLOSE, GRADIENT, TOPHAT and BLACKHAT. A circular structuring element/kernel is used for all types. The diameter of the kernel can be specified by diameterPix. For erosion the basic idea is just like soil erosion, it erodes away the boundaries of an object making it thinner. The dilation is the opposite transformation. The elements of the kernel contain: 0-background or 1-foreground. It is centered at each image pixel and defines the neighborhood pixels to be used. For grayscale erosion the new pixel value corresponds to the minimum value of the image pixels under the structuring element foreground. Similarly, for grayscale dilation the maximum of the neighborhood is used. The remaining transformations are: opening - erosion followed by dilation; closing - dilation followed by erosion; morphological gradient - difference between dilation and erosion; top hat - difference between input image and opening; black hat - difference between closing and input image. Image world coordinate system handling: The image world coordinate system is copied from the input image, only the image content is changed. The diameter of the structuring element is in pixel units, i.e., not scaled with the world pixel sizes in x and y. Missing data handling: This function does not handle missing data images. Fill in the missing data pixels and/or remove the missing data flag from the image before calling.

Keywords

binary, blackhat, close, erode, open, tophat, dilate

Parameters
Name	Type	Description
imageIn	CONST_OBJECT Image	Input image. Supported image types are uint8, uint16, int8, int16, int32, float32 and float64.
diameterPix	INT	The diameter of the circular structuring element/kernel in pixels. The value must be odd and between 3 and 51.
transform	ENUM MorphologicalTransform	The morphological transformation, possible types are: ERODE, DILATE, OPEN, CLOSE, GRADIENT, TOPHAT and BLACKHAT.

Return values
Name	Type	Description
imageOut	OBJECT Image	Morphology transformed image

Sample

imageOut = Image.morphology(imageIn, diameterPix, transform)

mosaic()

Short description

Crops an image into a vector of smaller tiles. The mosaic tiles can be specified to overlap. A valid tile must be completely within the source image, i.e., tiles that would partly extend outside the image at the right and bottom borders of the source image are not included in the output vector. The vector of tiles is sorted row wise so that all the tiles covering the uppermost part of the image come first.

Parameters
Name	Type	Description
image	CONST_OBJECT Image	The image.
tileWidth	INT	The width of a tile in pixels.
tileHeight	INT	The height of a tile in pixels.
xOverlap	INT	Optional overlap between tiles in the x-direction in pixels. Default is no overlap, i.e., 0 pixels.
yOverlap	INT	Optional overlap between tiles in the y-direction in pixels. Default is no overlap, i.e., 0 pixels.

Return values
Name	Type	Description
imageTiles	OBJECT Image	Vector of image tiles.
xTileCount	INT	Number of tiles in the x-direction.
yTileCount	INT	Number if tiles in the y-direction.

Sample

local imageTiles, nx, ny = Image.mosaic(im, 32, 32)

multiply()

Short description

Multiplies two images pixelwise. The images must be of equal size and pixel type. If there is underflow or overflow in the arithmetic operation, the output pixel value is clamped to the min and max limit of the pixel type, with an exception for images containing missing data, see below. Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. The operation is interpreted as operating on the world z-coordinate value. The second image is treated as a unit-less modifier and it must therefore have a standard image world coordinate system with pixel sizes all equal to 1 and origins equal to 0. Pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation. Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image. Note that it is possible to obtain 0 as result of the multiplication and that such pixels then will be considered as missing data in subsequent processing steps.

Keywords

arithmetic, scale, times

Parameters
Name	Type	Description
image1	CONST_OBJECT Image	The first source image.
image2	CONST_OBJECT Image	The second source image.

Return values
Name	Type	Description
result	OBJECT Image	The product image.

Sample

result = Image.multiply(image1, image2)

multiplyAddConstant()

Short description

Multiplies an image pixelwise by a constant alpha and then adds a second constant beta: alpha*Image + beta. If there is underflow or overflow in the arithmetic operation, the output pixel values are clamped to the min or max limit of the pixel data type, with an exception for images containing missing data, see below. Image world coordinate system handling: If the image has a non-default image world coordinate system, for example a height map, distance or range image, the operation is interpreted in image world coordinate units, e.g., millimeters, considering the z-origin and z-pixelsize. The image metadata from the input image is copied to the output image. Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.

Keywords

arithmetic, scale, offset

See also

Parameters
Name	Type	Description
image	CONST_OBJECT Image	The source image.
alpha	FLOAT	The constant to multiply with.
beta	FLOAT	The constant to add.

Return values
Name	Type	Description
result	OBJECT Image	The resulting image.

Sample

result = Image.multiplyAddConstant(image, alpha, beta)

multiplyAddConstantInplace()

Short description

Inplace version of Image.multiplyAddConstant function which modifies the input image. See base function for full documentation.

Keywords

arithmetic, scale, offset

See also

Image.multiplyAddConstant

Parameters
Name	Type	Description
image	OBJECT Image	The source image. This image is overwritten with the result image.
alpha	FLOAT	The constant to multiply with.
beta	FLOAT	The constant to add.

Return values
Name	Type	Description
result	OBJECT Image	Reference to the result image.

Sample

result = Image.multiplyAddConstantInplace(image, alpha, beta)

multiplyConstant()

Short description

Multiplies all pixels in the image with a constant value. If there is underflow or overflow in the arithmetic operation, the output pixel values are clamped to the min or max limit of the pixel data type, with an exception for images containing missing data, see below. Image world coordinate system handling: If the image has a non-default image world coordinate system, for example a height map, distance or range image, multiplication of the world z-value is done, considering the z-origin and z-pixelsize. The image metadata from the input image is copied to the output image. Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. Note that it is possible to obtain 0 as result of the multiplication and that such pixels then will be considered as missing data in subsequent processing steps.

Keywords

arithmetic, scale, times

Parameters
Name	Type	Description
image	CONST_OBJECT Image	The source image.
constant	FLOAT	The constant.

Return values
Name	Type	Description
result	OBJECT Image	The multiplied image.

Sample

result = Image.multiplyConstant(image, 2.0)

multiplyConstantInplace()

Short description

Inplace version of Image.multiplyConstant function which modifies the input image. See base function for full documentation.

Keywords

arithmetic, scale, times

Parameters
Name	Type	Description
image	OBJECT Image	The source image. This image is overwritten with the result image.
constant	FLOAT	The constant.

Return values
Name	Type	Description
result	OBJECT Image	Reference to the result image.

Sample

result = Image.multiplyConstantInplace(image, 2.0)

multiplyInplace()

Short description

Inplace version of the Image.multiply function which modifies the first input image to contain the product of the input images. See base function for full documentation.

Keywords

arithmetic, scale, times

Parameters
Name	Type	Description
image1	OBJECT Image	The first source image. This image is overwritten with the product.
image2	CONST_OBJECT Image	The second source image.

Return values
Name	Type	Description
result	OBJECT Image	Reference to the result image.

Sample

result = Image.multiplyInplace(image1, image2)

normalize()

Short description

Scales the raw pixel values linearly so that all pixels fit into a given range (lowerBound, upperBound). Keeps the world values constant. Target bounds outside the representable range of the image type are accepted. In that case, pixel values are clamped to the representable range. Image world coordinate system handling: The world coordinate system of the output image along the value axis z is chosen such that the world pixel values remains unchanged unless clamping occurs. For integer type images, rounding to integer raw pixel values will change the world values slightly. Other meta data are copied from the input image. Missing data handling: Pixels with missing data remain marked as missing in the output. For images with the missing data flag set, raw pixel values are clamped to 1 instead of 0 to avoid introducing more pixels marked as missing.

Keywords

contrast, intensity, scale, stretch, equalize

Parameters
Name	Type	Description
image	CONST_OBJECT Image	Input image. Supported image types are uint8, uint16, int8, int16, int32, float32 and float64.
lowerBound	FLOAT	Lower bound (raw pixel value). Default value is minimum value of underlying datatype.
upperBound	FLOAT	Upper bound (raw pixel value). Default value is maximum value of underlying datatype.
region	CONST_OBJECT Image.PixelRegion	Optional region of interest. If supplied, the operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small.

Return values
Name	Type	Description
normalizedImage	OBJECT Image	Normalized image

Sample

normalizedImage = Image.normalize(image)

pad()

Short description

Image padding, adds a border to the image. Image world coordinate system handling: The image world coordinate system is used to update the output image origin, it is calculated as follows: (Oxout, Oyout, Ozout) = (Oxin - pixelSizeX * leftPaddingPix, Oyin - pixelSizeY * topPaddingPix, Ozin), the world pixel sizes remain the same. The boundary paddings are in pixel units, i.e., not scaled with the world pixel sizes in x and y. Missing data handling: This function does not use the missing data flag. If the padding contains zeros it will be treated as missing data if the flag is on.

Keywords

replicate, extend

See also

Image.concatenate

Parameters
Name	Type	Description
imageIn	CONST_OBJECT Image	Input image. Supported image types are uint8, uint16, int8, int16, int32, float32, float64 and RGB.
topPaddingPix	INT	The top padding in pixels
bottomPaddingPix	INT	The bottom padding in pixels
leftPaddingPix	INT	The left padding in pixels
rightPaddingPix	INT	The right padding in pixels
borderType	ENUM BorderType	The border type to use for the padding, currently CONSTANT, REPLICATE, REFLECT and WRAP are available. If the border type is not CONSTANT the padding value is not used.
intensity	FLOAT	The padding intensity. In case the image type is RGB then an array of 3 elements (one per channel) must be provided. If the border type is not CONSTANT this value does not need to be specified.

Return values
Name	Type	Description
imageOut	OBJECT Image	Padded Image

Sample

imageOut = Image.pad(imageIn, topPaddingPix, bottomPaddingPix, leftPaddingPix, rightPaddingPix, borderType, intensity)

pow()

Short description

Applies an exponent to the value at each pixel. If there is underflow or overflow in the arithmetic operation, the output pixel value is clamped to the min and max limit of the pixel data type respectively. Image world coordinate system handling: The z-scale of the image is considered, but the operation is not implemented for images with z-origin different from 0.0. The image metadata from the input image is copied to the output image. Missing data handling: In case of an underflow in the arithmetic, values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.

Keywords

arithmetic, cube, exp, exponent, inverse, invert, sqr, sqrt, square, power

See also

Image.powInplace

Parameters
Name	Type	Description
image	CONST_OBJECT Image	The source image.
exponent	FLOAT	The exponent.

Return values
Name	Type	Description
result	OBJECT Image	The processed image.

Sample

result = Image.pow(image, exponent)

powInplace()

Short description

Inplace version of the Image.pow function which modifies the input image. See base function for full documentation.

Keywords

arithmetic, cube, exp, exponent, inverse, invert, sqr, sqrt, square, power

See also

Image.pow

Parameters
Name	Type	Description
image	OBJECT Image	The source image. This image is overwritten with the result image.
exponent	FLOAT	The exponent.

Return values
Name	Type	Description
result	OBJECT Image	A reference to the result image.

Sample

Image.powInplace(image, exponent)

renderPlane()

Short description

Renders a plane to an image, clamping values to the representable range of the image. The output image is of the same type as the input image. Image world coordinate system handling: The surface is rendered in the world space defined by the reference image, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the reference image is copied to the output image. Missing data handling: The missing data flag of the reference image is copied to the output image. If the flag is set, raw pixel values are clamped to 1 instead of 0 to avoid generating pixels with missing data.

Keywords

draw

See also

Image.renderPlaneInplace

Parameters
Name	Type	Description
image	CONST_OBJECT Image	The reference image defining the output image size, type and coordinate system.
plane	CONST_OBJECT Shape3D	The plane to render, should be a plane shape.

Return values
Name	Type	Description
renderedImage	OBJECT Image	The image with the rendered plane. Nil if an error occurred.

Sample

renderedImage = Image.renderPlane(image, plane)

renderPlaneInplace()

Short description

Inplace version of the Image.renderPlane function which modifies the input image by adding the value of a given plane. See base function for full documentation.

Keywords

draw

See also

Image.renderPlane

Parameters
Name	Type	Description
image	OBJECT Image	Reference input image. This image is overwritten with the result image.
plane	CONST_OBJECT Shape3D	The plane to render, must be a Shape3D plane.

Return values
Name	Type	Description
result	OBJECT Image	Reference to the result image.

Sample

result = Image.renderPlaneInplace(image, plane)

renderText()

Short description

Renders text into an image by modifying the pixel values. Image world coordinate system handling: The image world coordinate system is copied from the input image, only the image content is changed. The font parameters and text position are in pixel units, i.e., not scaled with the world pixel sizes in x and y. Missing data handling: This function does not use the missing data flag.

Keywords

characters, letters, draw

See also

Image.drawText, Image.renderTextInplace

Parameters
Name	Type	Description
image	OBJECT Image	The image to render the text into. Supported image types are uint8, uint16, int8, int16, int32, float32, float64 and RGB.
text	STRING	The characters that cannot be rendered using the specified font are replaced by question marks.
positionWorld	CONST_OBJECT Point	The position of the text inside the image, in world coordinates. The text is aligned to the bottom-left corner.
fontSizePix	INT	The font size in pixels.
fontThicknessPix	INT	The font line thickness radius in pixels. To calculate the overall thickness the following equation can be used: thickness=(fontThicknessPix*2+1).
value	FLOAT	The text (intensity/color) value. In case the image type is RGB then an array of 3 elements (one per channel) must be provided.

Return values
Name	Type	Description
image	OBJECT Image	Image with rendered text

Sample

image = Image.renderText(image, text, positionWorld, fontSizePix, fontThicknessPix, value)

renderTextInplace()

Short description

Inplace version of the Image.renderText function that modifies the input image. See base function for full documentation.

Keywords

characters, letters, draw

See also

Image.drawText, Image.renderText

Parameters
Name	Type	Description
image	OBJECT Image	The image to render the text into. This image is overwritten with the rendered text. Supported image types are uint8, uint16, int8, int16, int32, float32, float64 and RGB.
text	STRING	The characters that cannot be rendered using the specified font are replaced by question marks.
positionWorld	CONST_OBJECT Point	The position of the text inside the image, in world coordinates. The text is aligned to the bottom-left corner.
fontSizePix	INT	The font size in pixels.
fontThicknessPix	INT	The font line thickness radius in pixels. To calculate the overall thickness the following equation can be used: thickness=(fontThicknessPix*2+1).
value	FLOAT	The text (intensity/color) value. In case the image type is RGB then an array of 3 elements (one per channel) must be provided.

Return values
Name	Type	Description
result	OBJECT Image	Reference to the result image.

Sample

result = Image.renderTextInplace(image, text, positionWorld, fontSizePix, fontThicknessPix, value)

replace()

Short description

Replaces the image content in a specified region with the content of another image. The images must have the same pixel type. Image world coordinate system handling: The world coordinate systems of the input images are not used. The output will have the same coordinate system as the first input image. Missing data handling: Raw pixel values are copied as they are. If there are missing data within the region in the replacing image, the source image pixels will be replaced by missing data.

Parameters
Name	Type	Description
sourceImage	CONST_OBJECT Image	Base image onto which the other image is painted.
replacingImage	CONST_OBJECT Image	The image containing the information to replace with.
region	CONST_OBJECT Image.PixelRegion	The region to replace.

Return values
Name	Type	Description
result	OBJECT Image	The composed image.

Sample

local result = Image.replace(sourceImage, replacingImage, region)

replaceInplace()

Short description

Inplace version of the Image.replace function which modifies the first input image by replacing pixel values with pixel values from another image. See base function for full documentation.

Parameters
Name	Type	Description
sourceImage	OBJECT Image	Base image onto which the other image is painted.
replacingImage	CONST_OBJECT Image	The image containing the information to replace with.
region	CONST_OBJECT Image.PixelRegion	The region to replace.

Return values
Name	Type	Description
result	OBJECT Image	Reference to the result image.

Sample

local result = Image.replaceInplace(sourceImage, replacingImage, region)

resize()

Short description

Resizes an image to a given size in pixels. Different interpolation methods can be used. Image world coordinate system handling: The coordinate system of the output image will be slightly adjusted in relation to the input to take into account pixel size changes. Eg. both the origin and pixel size of the image will typically change. World positions in the image should be retained such that for example overlay graphics can remain on the same position after a rescaling. Values in z, both origin and pixel size, are copied directly from the input image. Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image.

Keywords

decimate, downsample, resample, subsample, transform, upsample, scale

Parameters
Name	Type	Description
image	CONST_OBJECT Image	Input image
width	INT	The width of the result
height	INT	The height of the result.
method	ENUM InterpolationMethod	The resampling method. Default is LINEAR.

Return values
Name	Type	Description
resizedImage	OBJECT Image	Image with new size.

Sample

resizedImage = Image.resize(image, 300, 400, "LINEAR")

resizeScale()

Short description

Resizes an image by a scale factor. Different interpolation methods can be used. Image world coordinate system handling: The coordinate system of the output image will be slightly adjusted in relation to the input to take into account pixel size changes. Eg. both the origin and pixel size of the image will typically change. World positions in the image should be retained such that for example overlay graphics can remain on the same position after a rescaling. Values in z, both origin and pixel size, are copied directly from the input image. Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image.

Keywords

decimate, downsample, resample, subsample, transform, upsample, scale

Parameters
Name	Type	Description
image	CONST_OBJECT Image	Input image
fx	FLOAT	Scaling factor along the x-axis.
fy	FLOAT	Scaling factor along the y-axis. Optional, if omitted the same as the x-scale is used.
method	ENUM InterpolationMethod	The resampling method. Default is LINEAR.

Return values
Name	Type	Description
resizedImage	OBJECT Image	Image with new size.

Sample

resizedImage = Image.resizeScale(image, 1.5, 1.5, "LINEAR")

rotate()

Short description

Rotates an image around the center of the image. Optionally a different origin of rotation can be specified. Image world coordinate system handling: If the image has a non-default image world coordinate system, for example after calibration or in a height map, distance or range image, the operation is interpreted in image world coordinate units, e.g., millimeters. The image metadata is copied from the input image and the transformed image is by default (output grid SAME) repainted onto this coordinate system. Using output grid FULL, the output image size and origin is set to fit the entire output. Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image.

Parameters
Name	Type	Description
image	CONST_OBJECT Image	Input image
rotationRad	FLOAT	Rotation in radians. As the image has a left-handed coordinate system, a positive rotation is in a counter clockwise direction.
origin	CONST_OBJECT Point	Optional origin of rotation if other than center of image. Represented as a 2D Point type.
method	ENUM InterpolationMethod	The resampling method.
grid	ENUM OutputGrid	The pixel grid to use for the output, default is SAME, the same as the input image.

Return values
Name	Type	Description
rotatedImage	OBJECT Image	The rotated image.

Sample

rotatedImage = Image.rotate(image, rotationRad)

rotate90()

Short description

Rotates an image +90, -90 or 180 degrees. A positive rotation is in the clockwise direction. The pixels are rearranged and no interpolation takes place, making the operation faster than a general rotation. Image world coordinate system handling: For plus and minus 90 degree rotations, the x- and y-pixel sizes are swapped so that the width and height are also swapped. The image origin is copied from the input image. Missing data handling: Missing data is rotated in the same way as the input image.

Parameters
Name	Type	Description
image	CONST_OBJECT Image	Input image
rotationSteps	INT	The number of 90-degree steps to rotate the image in, e.g. -1, 1 or 2. Other integers are allowed, representing the same rotations. A positive rotation is in a clockwise direction.

Return values
Name	Type	Description
rotatedImage	OBJECT Image	The rotated image.

Sample

rotatedImage = Image.rotate90(image, rotationSteps)

save()

Short description

Saves an image to the specified file path. Overwrites the file if it already exists. Supported pixel types are: UINT8, UINT16, INT8, INT16, INT32, FLOAT32 and FLOAT64. The format is defined by the file extension: .bmp: Bitmap, no data compression. (Optional compression parameter not supported). Image origin, pixel size and missing data flag are not saved. .png: PNG, lossless data compression. (Compression level can be controlled by compression parameter. Allowed values are "0" to "9". Default is "6".) Image origin, pixel size and missing data flag are not saved. For pixel types INT8, INT16, INT32, FLOAT32 and FLOAT64 the values are clamped to 0-255. .jpg: JPEG, lossy data compression. Not supported on all devices. (Quality can be controlled by compression parameter. Allowed values are "0" to "100". Default is "95") Image origin, pixel size and missing data flag are not saved. .json: JSON, no compression. (Optional compression parameter not supported). Image origin, pixel size and missing data flag are saved. .msgpack: MessagePack, no compression. (Optional compression parameter not supported). Image origin, pixel size and missing data flag are saved.

See also

Image.setOriginZ, Image.getOrigin

Parameters
Name	Type	Description
image	CONST_OBJECT Image	The image to save.
filepath	STRING	The path and name of the file to write the image to.
compression	STRING	Optional parameters controlling compression ratio for certain file formats.

Return values
Name	Type	Description
success	BOOL	Returns true on success.

Sample

Image.save(image, "private/image.bmp")

setAll()

Short description

Sets all raw pixel values in an image to the specified value. Currently only supports scalar pixel types, i.e., not RGB. Pixels with missing data are also set. Setting all pixels to zero on an image with the global missing data flag set, all pixels will be marked as missing.

See also

Image.setPixel

Parameters
Name	Type	Description
image	OBJECT Image	The image.
value	FLOAT	The raw pixel value to set.

Sample

Image.setAll(image, 0.0)

setColumn()

Short description

Fills in a column of an image with the value(s) provided. Note that this function operates inplace. If a scalar value is provided, all rows from startRow to the image height will be filled with the value. If the provided value(s) is a vector of length N, N rows will be filled with these values starting at row startRow. Coordinate system handling: The image world coordinate system is only considered along the value range. Missing data handling: A missing data image may be used as the target image. Values evaluating to the origin in z will become missing in the target.

Parameters
Name	Type	Description
image	OBJECT Image	The target image. All pixel types except RGB are supported.
values	FLOAT	The source profile.
column	INT	Index of column to fill, zero-based.
startRow	INT	The first row index to fill, zero-based. If no index is given 0 will be used.

Return values
Name	Type	Description
success	BOOL	True if values could be set.

Sample

local success = Image.setColumn(image, values, column, startRow)

setColumnProfile()

Short description

Fills in a column of an image with the values taken from a profile. Note that this function operates inplace. The values in the profile is filled into the image column starting at row startRow. The number of values set are equal to the length of the profile. Coordinate system handling: The image world coordinate system is only considered along the value range, i.e., the profile z origin and pixelsize is used to scale the profile before placing it in the image. The x and y coordinate of the profile and image are ignored and the values are simply placed in the designated image pixels. Missing data handling: If the source profile contains invalid points the target image must be a missing data image. Missing data is propagated from profile to image.

Parameters
Name	Type	Description
image	OBJECT Image	The target image. All pixel types except RGB are supported.
profile	CONST_OBJECT Profile	The source profile.
column	INT	Index of column to fill, zero-based.
startRow	INT	The first row index to fill, zero-based. If no index is given 0 will be used.

Return values
Name	Type	Description
success	BOOL	True if values could be set.

Sample

local success = Image.setColumnProfile(image, profile, column, startRow)

setMissingDataFlag()

Short description

Sets the missing data setting in the image. 0 means no missing data handling, 1 means that the value 0 is treated as missing data.

See also

Image.getMissingDataFlag

Parameters
Name	Type	Description
image	OBJECT Image
missingDataFlag	INT	0 means no missing data handling, 1 means that the value 0 is treated as missing data.

Sample

Image.setMissingDataFlag(image, 1)

setOrigin()

Short description

Sets the origin of the image world coordinate system in the image. The origin corresponds to the image world coordinate of the top-left pixel. If a 2D point is provided, the origin is unchanged in the z-direction.

See also

Parameters
Name	Type	Description
image	OBJECT Image
origin	CONST_OBJECT Point	A 3D point describing the world coordinate of the top-left image pixel.

Return values
Name	Type	Description
success	BOOL	Returns true if successfully set the origin.

Sample

local success = Image.setOrigin(image, origin)

setOriginZ()

Short description

Sets the z-origin of the image world coordinate system in the image.

See also

Image.adjustOriginZ, Image.setOrigin

Parameters
Name	Type	Description
image	OBJECT Image	Image object to update.
originZ	FLOAT	The new z-origin.

Sample

Image.setOriginZ(image, originZ)

setPixel()

Short description

Set the raw pixel value or a vector of pixel values in an image at position(s) (x,y) to the given raw pixel value. For monochrome image types this is a single float value, for RGB24 a vector of three float values in the order red, green, blue.

See also

Image.setAll, Image.getPixel

Parameters
Name	Type	Description
image	OBJECT Image	The image to set the pixels to
x	INT	The x coordinate, or a vector of x coordinates, of the pixel(s) to set.
y	INT	The y coordinate, or a vector of y coordinates, of the pixel(s) to set.
value	FLOAT	The raw pixel value, or a vector of RGB values, to set.

Sample

Image.setPixel(image, 5, 6, 127)
Image.setPixel(imageRGB, {5, 5}, {6, 7}, {0, 127, 255})

setPixelSize()

Short description

Sets the pixel size in world coordinates. If the size in the Z direction is omitted, the Z size is unchanged.

See also

Image.setPixelSizeZ, Image.getPixelSize

Parameters
Name	Type	Description
image	OBJECT Image
sizeX	FLOAT	The size of a pixel in the X dimension in world coordinate units.
sizeY	FLOAT	The size of a pixel in the Y dimension in world coordinate units.
sizeZ	FLOAT	The size of a pixel in the Z dimension in world coordinate units (optional).

Sample

Image.setPixelSize(image, sizeX, sizeY, sizeZ)

setPixelSizeZ()

Short description

Sets the pixel size in the z-dimension in world coordinates, e.g., the number of millimeters each pixel value integer increment corresponds to.

See also

Image.setPixelSize

Parameters
Name	Type	Description
image	OBJECT Image
sizeZ	FLOAT	The size/scale along the z-dimension.

Sample

Image.setPixelSizeZ(image, sizeZ)

setRow()

Short description

Fills in a row of an image with the value(s) provided. Note that this function operates inplace. If a scalar value is provided, all columns from startColumn to the image width will be filled with the value. If the provided value(s) is a vector of length N, N columns will be filled with these values starting at column startColumn. Coordinate system handling: The image world coordinate system is only considered along the value range. Missing data handling: A missing data image may be used as the target image. Values evaluating to the origin in z will become missing in the target.

Parameters
Name	Type	Description
image	OBJECT Image	The target image. All pixel types except RGB are supported.
values	FLOAT	The source data.
row	INT	Index of row to fill, zero-based.
startColumn	INT	The first column index to fill, zero-based. If no index is given 0 will be used.

Return values
Name	Type	Description
success	BOOL	True if values could be set.

Sample

local success = Image.setRow(image, values, row, startColumn)

setRowProfile()

Short description

Fills in a row of an image with the values taken from a profile. Note that this function operates inplace. The values in the profile is filled into the image row starting at column startColumn. The number of values set are equal to the length of the profile. Coordinate system handling: The image world coordinate system is only considered along the value range, i.e., the profile z origin and pixelsize is used to scale the profile before placing it in the image. The x and y coordinate of the profile and image are ignored and the values are simply placed in the designated image pixels. Missing data handling: If the source profile contains invalid points the target image must be a missing data image. Missing data is propagated from profile to image.

Parameters
Name	Type	Description
image	OBJECT Image	The target image. All pixel types except RGB are supported.
profile	CONST_OBJECT Profile	The source profile.
row	INT	Index of row to fill, zero-based.
startColumn	INT	The first column index to fill, zero-based. If no index is given 0 will be used.

Return values
Name	Type	Description
success	BOOL	True if values could be set.

Sample

local success = Image.setRowProfile(image, profile, row, startColumn)

sobel()

Short description

Applies the standard 3x3 Sobel filter operator to find gradients and edges in the x- and y-directions. Image world coordinate system handling: The Sobel filter kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image in the xy-dimensions. In the z-dimension, the z-origin is set to 0 but the z-pixelsize is inherited from the input image to be able to related ensuing thresholding of the output image to the input world z-scale. Missing data handling: This function does not accept missing data images, fill in the missing data pixels prior to calling this function.

Keywords

convolve, derivative, gradient, edge

Parameters
Name	Type	Description
image	CONST_OBJECT Image	Input image. Supported image types are uint8, uint16, int16, float32 and float64.
region	CONST_OBJECT Image.PixelRegion	Optional region of interest. If supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Pixel values outside the region are undefined.

Return values
Name	Type	Description
gx	OBJECT Image	Output image with gradient x.
gy	OBJECT Image	Output image with gradient y.

Sample

gx, gy = Image.sobel(image)

sobelMagnitude()

Short description

Calculates the magnitude of the standard 3x3 Sobel operator gradient responses dx and dy to find edges in the input image. Image world coordinate system handling: The Sobel filter kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image in the xy-dimensions. In the z-dimension, the z-origin is set to 0 but the z-pixelsize is inherited from the input image to be able to related ensuing thresholding of the output image to the input world z-scale. Missing data handling: This function does not accept missing data images, fill in the missing data pixels prior to calling this function.

Keywords

convolve, derivative, gradient, edge

See also

Image.canny, Image.laplace, Image.sobel

Parameters
Name	Type	Description
image	CONST_OBJECT Image	Input image. Supported image types are uint8, uint16, uint32, int8, int16, int32, float32 and float64.
region	CONST_OBJECT Image.PixelRegion	Optional region of interest. Enter the value nil to filter the entire image. If a non-empty region is supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small.
metric	ENUM MetricType	Select if the faster abs(dx)+abs(dy) or the more precise sqrt(dx^2+dy2) should be used. Default is 'ABS'.

Return values
Name	Type	Description
imageMag	OBJECT Image	Output image with gradient magnitude.

Sample

imageMag = Image.sobelMagnitude(image)

splitRGB()

Short description

Splits an RGB image into the individual R, G, B color components. The input RGB image must be of 8-bit RGB type.

Keywords

color

See also

Image.toRGB, Image.toGray

Parameters
Name	Type	Description
imageRGB	CONST_OBJECT Image	RGB image (8-bit) to convert.

Return values
Name	Type	Description
imageR	OBJECT Image	Red component as image.
imageG	OBJECT Image	Green component as image.
imageB	OBJECT Image	Blue component as image.

Sample

imageR, imageG, imageB = Image.splitRGB(imageRGB)

subtract()

Short description

Subtracts two images pixelwise. The images must be of equal size and pixel type. If there is underflow or overflow in the arithmetic operation, the output pixel value is clamped to the min and max limit of the pixel type, with an exception for images containing missing data, see below. Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. The operation is interpreted as operating on the world z-coordinate values. Pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation. For unsigned integer types it can be useful to first apply Image.adjustOriginZ() to image1 to avoid clamping the results to 0. For images A, B subtracting B from A would cause clamping when values in B are larger than those in A by such a large amount that the difference exceeds the Z-origin of A. By adjusting the origin of A to a smaller value this can be remedied. Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image. For missing data images, as the value 0 is reserved, clamping to 1 instead of 0 is done for underflows and when the pixel type is unsigned integer.

Keywords

arithmetic, difference, minus

See also

Image.difference, Image.subtractInplace

Parameters
Name	Type	Description
image1	CONST_OBJECT Image	The first source image.
image2	CONST_OBJECT Image	The second source image.

Return values
Name	Type	Description
result	OBJECT Image	The difference image.

Sample

result = Image.subtract(image1, image2)

subtractInplace()

Short description

Inplace version of the Image.subtract function which modifies the first input image to contain the difference of the input images. See base function for full documentation.

Keywords

arithmetic, difference, minus

See also

Image.difference, Image.subtract

Parameters
Name	Type	Description
image1	OBJECT Image	The first source image. This image is overwritten with the difference.
image2	CONST_OBJECT Image	The second source image.

Return values
Name	Type	Description
result	OBJECT Image	Reference to the result image.

Sample

result = Image.subtractInplace(image1, image2)

subtractPlane()

Short description

Subtracts a plane from an image. For every pixel, the corresponding plane z-value is subtracted. If there is underflow or overflow for integer type images, the output value is clamped to the min and max limit of the pixel data type. A partial region of operation may be selected, reducing the processing time. By setting autoAdjustOriginZ true for unsigned integer data, the origin of the result image will be adjusted to avoid clamping at zero. Using automatic origin adjustment on a partial region of the image will not compensate the pixel values outside the region for the new origin, such pixels will appear with an offset in global coordinates. Image world coordinate system handling: The plane is interpreted in world space and subtracted from the image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the input image is copied to the output image. Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, raw values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.

Keywords

gradient, ramp

Parameters
Name	Type	Description
image	CONST_OBJECT Image	The image.
plane	CONST_OBJECT Shape3D	The plane to subtract, must be a Shape3D plane.
region	CONST_OBJECT Image.PixelRegion	Region of the image where the plane should be subtracted, default is the full image. An empty region or nil are interpreted as the full image.
autoAdjustOriginZ	BOOL	Flag indicating if the origin of the output image should be adjusted to avoid clamping at zero. Default is false, using the same origin as the input image.

Return values
Name	Type	Description
resultImage	OBJECT Image	The image with the subtracted plane. Nil if an error occurred.

Sample

resultImage = Image.subtractPlane(image, plane, region, autoAdjustOriginZ)

subtractPlaneInplace()

Short description

Inplace version of the Image.subtractPlane function which modifies the input image by subtracting the value of a given plane. See base function for full documentation.

Keywords

gradient, ramp

Parameters
Name	Type	Description
image	OBJECT Image	The source image. This image is overwritten with the result image.
plane	CONST_OBJECT Shape3D	The plane to subtract, must be a Shape3D plane.
region	CONST_OBJECT Image.PixelRegion	Region of the image where the plane should be subtracted, default is the full image. An empty region or nil are interpreted as the full image.
autoAdjustOriginZ	BOOL	Flag indicating if the origin of the output image should be adjusted to avoid clamping at zero. Default is false, using the same origin as the input image.

Return values
Name	Type	Description
result	OBJECT Image	Reference to the result image.

Sample

result = Image.subtractPlaneInplace(image, plane, region, autoAdjustOriginZ)

subtractProfile()

Short description

Returns the image with the profile subtracted from all rows or all columns depending on the dimension argument. The dimension argument is optional and if not provided processing is done row by row. Image world coordinate system handling: The input profile is in world coordinates. The result image will have originZ set to zero. Missing data handling: For missing data in the image, the pixels with missing data will still be zero. For missing data in the profile, the image data will be unchanged. If missing data note that the minimum value is always 1 for valid pixels.

Parameters
Name	Type	Description
image	CONST_OBJECT Image	The image.
profile	CONST_OBJECT Profile	The profile.
dimension	ENUM ProcessingDimension	Optional processing dimension (row/column).

Return values
Name	Type	Description
result	OBJECT Image	Image with profile subtracted along processing dimension.

Sample

result = Image.subtractProfile(image, profile, dimension)

subtractProfileInplace()

Short description

Inplace version of the Image.subtractProfile function that modifies the input image. See base function for full documentation.

Parameters
Name	Type	Description
image	OBJECT Image	The image. This image is overwritten with the result image.
profile	CONST_OBJECT Profile	The profile.
dimension	ENUM ProcessingDimension	Optional processing dimension (row/column).

Return values
Name	Type	Description
result	OBJECT Image	Reference to the result image.

Sample

result = Image.subtractProfileInplace(image, profile, dimension)

thin()

Short description

Applies a morphological thinning, also known as skeletonization, using the Guo-Hall algorithm. It is typically performed on an already binarized input image. Zeros in the input image are be interpreted as background pixels. Note: The algorithm can be slow for large images with many non-zeros (large binary objects). Consider operating on regions of interest if possible. The output is a binary image with the skeleton indicated by pixels set to the maximum value of the pixel type, e.g., 255 for the uint8 type. Image world coordinate system handling: The image world coordinate system is not considered in this function. The output image inherits the x,y origin and x,y pixelsize, but the z-origin is reset to 0 and z-pixelsize to 1. Missing data handling: The missing data flag is reset by this function as the output is a binary image.

Keywords

morphology, skeleton

See also

Image.PixelRegion.thin

Parameters
Name	Type	Description
image	CONST_OBJECT Image	Input image, expected to be binary. Supported image types are uint8 and uint16.
region	CONST_OBJECT Image.PixelRegion	Optional region of interest. If supplied, the operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small.

Return values
Name	Type	Description
skeletonImage	OBJECT Image	Skeleton image.

Sample

skeletonImage = Image.thin(image)

threshold()

Short description

Threshold the image by keeping all pixels with a value between lowerThreshold and upperThreshold (inclusive). Return the result as a PixelRegion object. Image world coordinate system handling: The input thresholds are interpreted in the image world coordinate system considering the z-origin and z-pixelsize, e.g., in millimeter scale if the image would represent a range image with z-origin different from 0 of a z-pixelsize different from 1. A conversion is done within the function to raw pixel value thresholds. Missing data handling: Missing data pixels are excluded from the output PixelRegion object.

Keywords

background, blob, foreground, region, segmentation

Parameters
Name	Type	Description
image	CONST_OBJECT Image	Input image.
lowerThreshold	FLOAT	Lower threshold. Expressed in image world coordinates if applicable.
upperThreshold	FLOAT	Upper threshold. Optional, default is no upper threshold (only include pixels larger than the lower threshold)
region	CONST_OBJECT Image.PixelRegion	Optional region of interest. If supplied, the threshold operation is only performed within this region. This can save a lot of computation time, if the region is small.

Return values
Name	Type	Description
region	OBJECT Image.PixelRegion	Pixel region containing all pixels with value between the thresholds.

Sample

region = Image.threshold(image, 1, 255) -- Gets a region containing all non-zero values of an uint8 image

thresholdCompare()

Short description

Threshold an image by pixelwise comparison with a reference image. All pixels with a value greater than or equal to the corresponding reference image value are included in the output PixelRegion object. An optional margin (positive or negative) may be provided, adjusting the reference image values prior to the comparison. A larger positive margin results in fewer included pixels. The optional flag findBright may be set to false, returning the region where the image is lower/darker than the reference image. A region of interest can be provided, limiting the processing to that region. The images must be of the same pixel type and be of equal size. This function gives a PixelRegion objects as output, to get a binary image as output use binarizeCompare instead. Image world coordinate system handling: To allow for an efficient comparison, the z-pixelsizes of the input images must be equal but the z-offsets may differ. The margin parameter is interpreted in image world coordinates, e.g., as a millimeter margin if the input is a range image. Missing data handling: Missing data pixels are excluded from the output PixelRegion object.

Keywords

adaptive, background, blob, foreground, region, segmentation, binarize

Parameters
Name	Type	Description
image	CONST_OBJECT Image	Input image to threshold.
referenceImage	CONST_OBJECT Image	Reference image to compare the input image with.
marginWorld	FLOAT	Optional margin added to the reference image. Default value is 0.
findBright	BOOL	Optional flag indicating if pixels brighter/higher or darker/lower than the reference image should be included. Default is true, returning brighter pixels.
regionOfInterest	CONST_OBJECT Image.PixelRegion	Optional region of interest. If supplied, the threshold operation is only performed within this region. This can save a lot of computation time, if the region is small. The default region is the entire image.

Return values
Name	Type	Description
region	OBJECT Image.PixelRegion	PixelRegion object containing all pixels passing the comparison operation.

Sample

region = Image.thresholdCompare(image, referenceImage, marginWorld, findBright, regionOfInterest)

thresholdPlane()

Short description

Thresholds the image by keeping all pixels with a world value between lowerThreshold and upperThreshold relative to the provided plane (inclusive). Returns the result as a PixelRegion object. Thresholding values strictly below or above the reference plane is also supported, using relative thresholds with the same sign. Image world coordinate system handling: The plane is interpreted in world space which is compared with image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. Thresholds are interpreted in the world coordinate system. Missing data handling: No pixel marked as missing is included in the output region.

Keywords

adaptive, background, blob, foreground, region, segmentation, binarize

Parameters
Name	Type	Description
image	CONST_OBJECT Image	Input image
lowerThreshold	FLOAT	Lower threshold relative to plane.
upperThreshold	FLOAT	Upper threshold relative to plane.
plane	CONST_OBJECT Shape3D	The plane, represented as a Shape3D, to which the lower and upper thresholds are related. The shape type must be a plane.
region	CONST_OBJECT Image.PixelRegion	Optional region of interest. If supplied, the threshold operation is only performed within this region. This can save a lot of computation time, if the region is small.

Return values
Name	Type	Description
thresholdedRegion	OBJECT Image.PixelRegion	Pixel region containing all pixels with value between the thresholds relative to the plane.

Sample

thresholdedRegion = Image.thresholdPlane(image, lowerThreshold, upperThreshold, plane, region)

toGray()

Short description

Converts an RGB image into a gray value image.

Keywords

RGB, grey

Parameters
Name	Type	Description
imageRGB	CONST_OBJECT Image	RGB image (8-bit) to convert.

Return values
Name	Type	Description
imageGray	OBJECT Image	Gray value image of uint8 pixel type.

Sample

imageGray = Image.toGray(imageRGB)

toHSV()

Short description

Converts an RGB image into individual HSV color space components. The Hue-component is usually represented as an angle in the interval [0,360], but to fit in a uint8 image the value is divided by 2 to be in the interval [0,180].

Keywords

HSL, RGB, hue, saturation, color

Parameters
Name	Type	Description
imageRGB	CONST_OBJECT Image	RGB image (8-bit) to convert.

Return values
Name	Type	Description
imageH	OBJECT Image	Hue image, uint8 pixel type and in range [0,180]
imageS	OBJECT Image	Saturation image, uint8 pixel type and in range [0,255]
imageV	OBJECT Image	Value image, uint8 pixel type and in range [0,255]

Sample

imageH, imageS, imageV = Image.toHSV(imageRGB)

toLab()

Short description

Converts an RGB image into individual Lab color space components.

Keywords

RGB, color

Parameters
Name	Type	Description
imageRGB	CONST_OBJECT Image	RGB image (8-bit) to convert.

Return values
Name	Type	Description
imageL	OBJECT Image	Lightness image, uint8 pixel type and in range [0,255]
imageA	OBJECT Image	'a' color component image, uint8 pixel type and in range [1,255]
imageB	OBJECT Image	'b' color component image, uint8 pixel type and in range [1,255]

Sample

imageL, imageA, imageB = Image.toLab(imageRGB)

toMatrix()

Short description

Creates a matrix from a monochrome image. Each entry in the matrix corresponds to the pixel value scaled by the image world Z coordinates. Missing data is set to NaN in the matrix.

Parameters
Name	Type	Description
inputImage	CONST_OBJECT Image	The input image.

Return values
Name	Type	Description
matrix	OBJECT Matrix	The matrix with the image content.

Sample

local matrix = Image.toMatrix(inputImage)

toPixelCoordinate()

Short description

Converts an image world coordinate to a pixel coordinate.

See also

Image.toPixelZ, Image.toWorldCoordinate

Parameters
Name	Type	Description
image	CONST_OBJECT Image
worldCoordinate	CONST_OBJECT Point	The world coordinate point.

Return values
Name	Type	Description
pixelCoordinate	OBJECT Point	Returns the pixel coordinate.

Sample

local pixelCoordinate = Image.toPixelCoordinate(image, worldCoordinate)

toPixelZ()

Short description

Converts a z world coordinate value to a raw pixel value using the image world coordinate system supplied by the input reference image. The mapping pixelValue = (worldZCoordinate - originZ)/pixelSizeZ is made.

See also

Image.toWorldZ, Image.toPixelCoordinate

Parameters
Name	Type	Description
refImage	CONST_OBJECT Image	Image carrying the image world coordinate system. No other information from the image is used.
worldZCoordinate	FLOAT	World z coordinate(s), e.g., millimeters.

Return values
Name	Type	Description
pixelValue	FLOAT	Raw pixel value(s).

Sample

local pixelValue = Image.toPixelZ(image, worldZCoordinate)

toPointCloud()

Short description

Creates a pointcloud from image(s). Typically one heightmap input image is used in which the pixel pitch is constant in each dimension. The alternative use cases are to supply separate images for either x and z or for x, y and z coordinates. In total there are three ways this can be used: 1. Image.toPointCloud(range, true/false, intensity, region) 2. Image.toPointCloud({X, Z}, true/false, intensity, region) 3. Image.toPointCloud({X, Y, Z}, true/false, intensity, region) In case 1 the pixel sizes and origin of the range image is used to create the X and Y coordinates. In case 2 the pixel sizes and origin of of Z is used to create the Y coordinates in the output. In case 3 all positions are uniquely determined by the input images X, Y and Z. Pixel sizes and origin in the input images are unused. The intensity and region inputs are optional and can be used to set the intensity of the output pointcloud and to remove points respectively. Image world coordinate system handling: in general the image world coordinate system is used to create the pointcloud, i.e. the (x, y, z)-pixel sizes and origins are used to create the (x, y, z)-components of the pointcloud. For details see the longer text above. Missing data handling: For images with missing data it is possible to select to keep or remove the missing points. If missing points are kept they are marked as such in the pointcloud and will be black in intensity. If they are removed the grid structure of the image is lost and the point cloud will be considered an unordered point cloud.

Keywords

extrude

See also

Image.PixelRegion.toPoints3D

Parameters
Name	Type	Description
image	CONST_OBJECT Image	The source image(s) with range/depth information. Either one range image or 3 coordinate images (X, Y and Z).
removeMissing	BOOL	Select if points that are missing data should be removed or not. For images without missing data this has no effect. Default is false.
intensity	CONST_OBJECT Image	Optional uint8 image that will be used for intensity information for each point. The pixel values are divided by 255 to create a number in the range [0,1] for the pointcloud intensity.
region	CONST_OBJECT Image.PixelRegion	Optional PixelRegion. If supplied, only points within the region are converted.

Return values
Name	Type	Description
pointcloud	OBJECT PointCloud	The resulting pointcloud.

Sample

local pointcloud = Image.toPointCloud(image, removeMissing, intensity, region)

toRGB()

Short description

Creates an RGB image from three grayscale images. The input images must be of uint8 type.

Keywords

color

See also

Image.toRGB, Image.toType, Image.toGray

Parameters
Name	Type	Description
imageR	CONST_OBJECT Image	Gray value image of uint8 type.
imageG	CONST_OBJECT Image	Gray value image of uint8 type.
imageB	CONST_OBJECT Image	Gray value image of uint8 type.
colorSpace	ENUM ColorSpace	The color space the input images represent.

Return values
Name	Type	Description
imageRGB	OBJECT Image	RGB image (8-bit).

Sample

imageRGB = Image.toRGB(imageR, imageG, imageB, colorSpace)

toSquarePixels()

Short description

Resizes an image to have square pixels, i.e., to have equal pixelsizes in the x and y dimensions. Having square pixels is sometimes required for further processing. Image world coordinate system handling: The coordinate system of the output image will be slightly adjusted in relation to the input to take into account pixel size changes. Eg. both the origin and pixel size of the image will typically change. World positions in the image should be retained such that for example overlay graphics can remain on the same position after a rescaling. Values in z, both origin and pixel size, will be copied directly from the input image. Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image.

Keywords

resample, scale, transform, anisotropic

Parameters
Name	Type	Description
image	CONST_OBJECT Image	Input image
upsample	BOOL	Select if to upsample one axis or downsample the other. Default is false.
method	ENUM InterpolationMethod	The resampling method. Default is LINEAR.

Return values
Name	Type	Description
squarePixelImage	OBJECT Image	Image with square pixels.

Sample

squarePixelImage = Image.toSquarePixels(image)

toString()

Short description

Gets a user-friendly string description of the image, containing all properties but no actual pixel values.

Parameters
Name	Type	Description
image	CONST_OBJECT Image	The image to describe.

Return values
Name	Type	Description
str	STRING	User-friendly description of the image.

Sample

str = Image.toString(image)

toType()

Short description

Converts an image to a new image of specified pixel type. The raw pixel values are casted and there may be underflow/overflow effects when casting to a type of lower capacity. For example, the value 256 in a uint16 image will overflow to 0 if converted to a uint8 type. To avoid such effects, clamp the input pixel values to the min and max values of the target pixel type. Supports only monochrome image types, for the RGB24 type there are more specific conversion functions toGray() and toRGB().

Parameters
Name	Type	Description
image	CONST_OBJECT Image	The image to be converted.
type	ENUM ImageType	The pixel type, e.g., UINT8, INT16, FLOAT64).

Return values
Name	Type	Description
convertedImage	OBJECT Image	Returns the image of specified type or nil.

Sample

local convertedImage = Image.toType(image, "UINT8")

toWorldCoordinate()

Short description

Converts a pixel coordinate to an image world coordinate.

See also

Image.toWorldZ, Image.toPixelCoordinate

Parameters
Name	Type	Description
image	CONST_OBJECT Image	The image
pixelCoordinate	CONST_OBJECT Point	The pixel coordinate point.

Return values
Name	Type	Description
worldCoordinate	OBJECT Point	Returns the world coordinate.

Sample

local worldCoordinate = Image.toWorldCoordinate(image, pixelCoordinate)

toWorldZ()

Short description

Converts a pixel raw value to a z world coordinate value using the image world coordinate system supplied by the input reference image. The mapping worldZCoordinate = pixelValue*pixelSizeZ + originZ is made.

Parameters
Name	Type	Description
image	CONST_OBJECT Image	Image carrying the image world coordinate system. No other information from the image is used.
pixelValue	FLOAT	Raw pixel value(s).

Return values
Name	Type	Description
worldZCoordinate	FLOAT	World z coordinate(s), e.g., millimeters.

Sample

local worldZCoordinate = Image.toWorldZ(image, pixelValue)

transform()

Short description

Applies a linear geometric transform to an image. The result image uses the same pixel grid as the input image, if the SAME output grid is selected. Image world coordinate system handling: If the image has a non-default image world coordinate system, for example after calibration or in a height map, distance or range image, the operation is interpreted in image world coordinate units, e.g., millimeters. The image metadata is copied from the input image and the transformed image is by default (output grid SAME) repainted onto this coordinate system. Using output grid FULL, the output image size and origin is set to fit the entire output. Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image.

Keywords

linear, rotate, scale, shear, shift, warp

Parameters
Name	Type	Description
image	CONST_OBJECT Image	Input image.
transform	CONST_OBJECT Transform	A linear transform defined by a Transform object.
method	ENUM InterpolationMethod	The resampling method. Default is NEAREST.
grid	ENUM OutputGrid	The pixel grid to use for the output, default is SAME, the same as the input image.

Return values
Name	Type	Description
transformedImage	OBJECT Image	Transformed image.

Sample

transformedImage = Image.transform(image, transform, method)

transformInto()

Short description

Applies a linear geometric transform to an image and writes the result into the pixel grid defined by the destination image. The pixel grid and coordinate system of the destination image is used for transform operation. Compared to the Image.transform function, this function gives a higher degree of control over the following parameters: - The size of the output image - The pixel sizes of the output image - The world origin of the output image All the above properties are set by the input destination image. For example, a unit transform where the destination image has a world coordinate system different from the input image will resample the image. Image world coordinate system handling: If the image or destination image has a non-default image world coordinate system, for example after calibration or in a height map, distance or range image, the operation is interpreted in image world coordinate units, e.g., millimeters. The image metadata is kept in the destination image and the transformed image is painted onto this coordinate system. Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image. The missing data flags of the input and destination images must match.

Keywords

linear, rotate, scale, shear, shift, warp

Parameters
Name	Type	Description
sourceImage	CONST_OBJECT Image	Source image.
transform	CONST_OBJECT Transform	A linear transform defined by a Transform object.
destinationImage	OBJECT Image	Destination image, the output will be placed into this image. The image size, pixels sizes and world origin from this image are used.
method	ENUM InterpolationMethod	The resampling method. Default is NEAREST.

Return values
Name	Type	Description
transformedImage	OBJECT Image	A reference to the input destinationImage. Nil on failure.

Sample

transformedImage = Image.transformInto(sourceImage, transform, destinationImage, method)

transformInto3D()

Short description

Applies a 3D linear geometric transform to an image and writes the result into the pixel grid defined by the destination image. Compared to the transformInto function, this function adds the possibility for 3D tilts. The function is typically used for heightmap image data. The pixel grid and coordinate system of the destination image are used for the transform operation. Compared to the Image.transform function, this function gives a higher degree of control over the following parameters: - The size of the output image - The pixel sizes of the output image - The world origin of the output image All the above properties are set by the input destination image. For example, a unit transform where the destination image has a world coordinate system different from the input image will resample the image. Image world coordinate system handling: If the image or reference image has a non-default image world coordinate system, for example after calibration or in a height map, distance or range image, the operation is interpreted in image world coordinate units, e.g., millimeters. The image metadata is copied from the reference image and the transformed image is repainted onto this coordinate system. Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image.

Keywords

linear, rotate, scale, shear, shift, warp

Parameters
Name	Type	Description
sourceImage	CONST_OBJECT Image	Source image.
transform	CONST_OBJECT Transform	A linear affine 3D transform defined by a Transform object.
destinationImage	OBJECT Image	Destination image, the output will be placed into this image. The image size, pixels sizes and world origin from this image are used.
method	ENUM InterpolationMethod	The resampling method. Default is NEAREST.
splatX	INT	The influence distance of a source point in the target image x direction. Default is 3.
splatY	INT	The influence distance of a source point in the target image y direction. Defaults to splatX if unset.
clearTarget	BOOL	Select if the destinationImage should be reset to missing data before transforming the source image into it.

Return values
Name	Type	Description
transformedImage	OBJECT Image	A reference to the input destinationImage. Nil on failure.

Sample

transformedImage = Image.transformInto3D(sourceImage, transform, destinationImage, method)

warpSector()

Short description

Warps the inner area of a sector shape to a rectilinear Cartesian grid.

Keywords

rectify, unwrap

See also

Image.cropRectify, Image.transform

Parameters
Name	Type	Description
image	CONST_OBJECT Image	Input image.
sector	CONST_OBJECT Shape	A sector shape defining the area in the source image to warp from.
interpolation	ENUM InterpolationMethod	Interpolation method to use. Currently only LINEAR is available.

Return values
Name	Type	Description
warpedImage	OBJECT Image	The warped image, or nil on failure.

Sample

warpedImage = Image.warpSector(image, sector, interpolation)

Image.Calibration

Overview

Image.Calibration.CameraModel

Short description

Calibration result object of single camera. These objects can be stored to and loaded from file. The results of the camera calibration satisfy the camera transformation equation from world to the image coordinate system: xp = KD([R|t] * X) K = [fx s cx, 0 fy cy, 0 0 1] D = Brown–Conrady lens model: k1, k2, p1, p2, k3 R = [r11 r12 r13, r21 r22 r23, r31 r32 r33] t = [tx ty tz]^T

Functions

create()

Short description

Create a instance for the calibration result handling

Return values
Name	Type	Description
cameraModel	OBJECT Image.Calibration.CameraModel	The calibration result object instance.

Sample

cameraModel = Image.Calibration.CameraModel.create()

getCalibrationImageSize()

Short description

Get the image size for which the calibration is valid.

Parameters
Name	Type	Description
cameraModel	CONST_OBJECT Image.Calibration.CameraModel	The instance to use.

Return values
Name	Type	Description
imageWidth	INT	The image width for which the calibration is valid.
imageHeight	INT	The image height for which the calibration is valid.

Sample

local imageWidth, imageHeight = Image.Calibration.CameraModel.getCalibrationImageSize(cameraModel)

getCameraID()

Short description

Get the unique camera identifier.

Parameters
Name	Type	Description
cameraModel	CONST_OBJECT Image.Calibration.CameraModel	The instance to use.

Return values
Name	Type	Description
cameraID	STRING	The unique camera identifier.

Sample

local cameraID = Image.Calibration.CameraModel.getCameraID(cameraModel)

getEulerAngles()

Short description

Get the Euler angle representation (yaw, pitch, roll) of the transform into camera coordinates (in degree).

Parameters
Name	Type	Description
cameraModel	CONST_OBJECT Image.Calibration.CameraModel	The instance to use.

Return values
Name	Type	Description
yaw	FLOAT	The rotation around x-axis in degree.
pitch	FLOAT	The rotation around y-axis in degree.
roll	FLOAT	The rotation around z-axis in degree.

Sample

local yaw, pitch, roll = Image.Calibration.CameraModel.getEulerAngles(cameraModel)

getFocalDistance()

Short description

Get the camera model focus setting parameter.

Parameters
Name	Type	Description
cameraModel	CONST_OBJECT Image.Calibration.CameraModel	The instance to use.

Return values
Name	Type	Description
focalDistance	FLOAT	Distance from the camera to the plane of best image sharpness.
unit	STRING	Focal distance unit. Default is mm.

Sample

local focalDistance, unit = Image.Calibration.CameraModel.getFocalDistance(cameraModel)

getIntrinsicK()

Short description

Get the intrinsic camera matrix.

Parameters
Name	Type	Description
cameraModel	CONST_OBJECT Image.Calibration.CameraModel	The instance to use.

Return values
Name	Type	Description
intrinsic	OBJECT Matrix	A 3x3 matrix with the intrinsic camera parameters: K = [fx s cx, 0 fy cy, 0 0 1]

Sample

local intrinsic = Image.Calibration.CameraModel.getIntrinsicK(cameraModel)

getPosition()

Short description

Returns the position of the camera center as a 3D Point. If no extrinsic calibration is available the position will be in origin (0, 0, 0).

Parameters
Name	Type	Description
cameraModel	CONST_OBJECT Image.Calibration.CameraModel	The instance to use.

Return values
Name	Type	Description
center	OBJECT Point	Camera center world position as a 3D point.

Sample

local center = Image.Calibration.CameraModel.getPosition(cameraModel)

getProjectionMatrix()

Short description

Get the 3x4 projection matrix P = K[R|t]. Transformation xp = K*(R*Xw + T), with xp = [u/z, v/z, z/z] = [x,y,1] in homogeneous coordinates and Xw = [X,Y,Z] in 3D world coordinates.

Parameters
Name	Type	Description
cameraModel	CONST_OBJECT Image.Calibration.CameraModel	The instance to use.

Return values
Name	Type	Description
projectionMatrix	OBJECT Matrix	A 3x4 projection matrix P = K[R

Sample

local projectionMatrix = Image.Calibration.CameraModel.getProjectionMatrix(cameraModel)

getSensorToWorldDistortion()

Short description

Get the lens distortion coefficients [k1, k2, p1, p2, k3].

Parameters
Name	Type	Description
cameraModel	CONST_OBJECT Image.Calibration.CameraModel	The instance to use.

Return values
Name	Type	Description
k1	FLOAT	Second order radial lens distortion coefficient.
k2	FLOAT	Fourth order radial lens distortion coefficient.
p1	FLOAT	First tangential lens distortion coefficient.
p2	FLOAT	Second tangential lens distortion coefficient.
k3	FLOAT	Sixth order radial lens distortion coefficient.

Sample

local k1, k2, p1, p2, k3 = Image.Calibration.CameraModel.getSensorToWorldDistortion(cameraModel)

getTransform()

Short description

Returns the pose of the camera as Transform object.

Parameters
Name	Type	Description
cameraModel	CONST_OBJECT Image.Calibration.CameraModel	The instance to use.

Return values
Name	Type	Description
transform	OBJECT Transform	Rigid transformation from world to camera coordinates [R,t].

Sample

local transform = Image.Calibration.CameraModel.getTransform(cameraModel)

getWorldToSensorDistortion()

Short description

Get the lens distortion coefficients [k1, k2, p1, p2, k3].

Parameters
Name	Type	Description
cameraModel	CONST_OBJECT Image.Calibration.CameraModel	The instance to use.

Return values
Name	Type	Description
k1	FLOAT	Second order radial lens distortion coefficient.
k2	FLOAT	Fourth order radial lens distortion coefficient.
p1	FLOAT	First tangential lens distortion coefficient.
p2	FLOAT	Second tangential lens distortion coefficient.
k3	FLOAT	Sixth order radial lens distortion coefficient.

Sample

local k1, k2, p1, p2, k3 = Image.Calibration.CameraModel.getWorldToSensorDistortion(cameraModel)

getXMLVersionTag()

Short description

Get the version tag of the XML file.

Parameters
Name	Type	Description
cameraModel	CONST_OBJECT Image.Calibration.CameraModel	The instance to use.

Return values
Name	Type	Description
versionTag	STRING	The version tag of the XML.

Sample

local versionTag = Image.Calibration.CameraModel.getXMLVersionTag(cameraModel)

load()

Short description

Load calibration result object from a file. This function is deprecated, please use Object.save/load instead.

See also

Object.load

Parameters
Name	Type	Description
fileName	STRING	Filename, including path and file extension.

Return values
Name	Type	Description
cameraModel	OBJECT Image.Calibration.CameraModel	The calibration result object or nil

Sample

local cameraModel = Image.Calibration.CameraModel.load("private/CalibrationResult.xml)

save()

Short description

Save calibration result object to a file. This function is deprecated, please use Object.save/load instead.

See also

Object.save

Parameters
Name	Type	Description
cameraModel	CONST_OBJECT Image.Calibration.CameraModel	The instance to use.
fileName	STRING	Filename, including path and file extension.

Return values
Name	Type	Description
success	BOOL	Returns true if the file is written correctly.

Sample

local success = Image.Calibration.CameraModel.save(cameraModel, "private/CalibrationResult.xml")

setCalibrationImageSize()

Short description

Set the image size for which the calibration is valid.

Parameters
Name	Type	Description
cameraModel	OBJECT Image.Calibration.CameraModel	The instance to use.
imageWidth	INT	The image width for which the calibration is valid.
imageHeight	INT	The image height for which the calibration is valid.

Sample

Image.Calibration.CameraModel.setCalibrationImageSize(cameraModel, imageWidth, imageHeight)

setCameraID()

Short description

Set the unique camera identifier.

Parameters
Name	Type	Description
cameraModel	OBJECT Image.Calibration.CameraModel	The instance to use.
cameraID	STRING	The unique camera identifier.

Sample

Image.Calibration.CameraModel.setCameraID(cameraModel, cameraID)

setFocalDistance()

Short description

Set the camera model focus setting parameter.

Parameters
Name	Type	Description
cameraModel	OBJECT Image.Calibration.CameraModel	The instance to use.
focalDistance	FLOAT	Distance from the camera to the plane of best image sharpness.
unit	STRING	Focal distance unit. Default is mm.

Sample

Image.Calibration.CameraModel.setFocalDistance(cameraModel, focalDistance, unit)

setIntrinsicK()

Short description

Set the intrinsic camera matrix.

Parameters
Name	Type	Description
cameraModel	OBJECT Image.Calibration.CameraModel	The instance to use.
intrinsic	OBJECT Matrix	A 3x3 matrix with the intrinsic camera parameters: K = [fx s cx, 0 fy cy, 0 0 1]

Sample

Image.Calibration.CameraModel.setIntrinsicK(cameraModel, intrinsic)

setProjectionMatrix()

Short description

Set the 3x4 projection matrix P = K[R|t].

Parameters
Name	Type	Description
cameraModel	OBJECT Image.Calibration.CameraModel	The instance to use.
projectionMatrix	OBJECT Matrix	A 3x4 projection matrix P = K[R

Sample

Image.Calibration.CameraModel.setProjectionMatrix(cameraModel, projectionMatrix)

setSensorToWorldDistortion()

Short description

Set the lens distortion coefficients [k1, k2, p1, p2, k3].

Parameters
Name	Type	Description
cameraModel	OBJECT Image.Calibration.CameraModel	The instance to use.
k1	FLOAT	Set second order radial lens distortion coefficient.
k2	FLOAT	Set fourth order radial lens distortion coefficient.
p1	FLOAT	Set first tangential lens distortion coefficient.
p2	FLOAT	Set second tangential lens distortion coefficient.
k3	FLOAT	Set sixth order radial lens distortion coefficient.

Sample

local transform = Image.Calibration.CameraModel.setSensorToWorldDistortion(cameraModel, k1, k2, p1, p2, k3)

setTransform()

Short description

Set the pose transformation of the camera as Transform object.

Parameters
Name	Type	Description
cameraModel	OBJECT Image.Calibration.CameraModel	The instance to use.
transform	OBJECT Transform	Rigid transformation describing the transformation from world to camera coordinates [R,t].

Sample

local transform = Image.Calibration.CameraModel.setTransform(cameraModel, transform)

setWorldToSensorDistortion()

Short description

Set the lens distortion coefficients [k1, k2, p1, p2, k3].

Parameters
Name	Type	Description
cameraModel	OBJECT Image.Calibration.CameraModel	The instance to use.
k1	FLOAT	Set second order radial lens distortion coefficient.
k2	FLOAT	Set fourth order radial lens distortion coefficient.
p1	FLOAT	Set first tangential lens distortion coefficient.
p2	FLOAT	Set second tangential lens distortion coefficient.
k3	FLOAT	Set sixth order radial lens distortion coefficient.

Sample

local transform = Image.Calibration.CameraModel.setWorldToSensorDistortion(cameraModel, k1, k2, p1, p2, k3)

toString()

Short description

Gets a short string description of the camera model.

Parameters
Name	Type	Description
cameraModel	CONST_OBJECT Image.Calibration.CameraModel	The camera model object.

Return values
Name	Type	Description
str	STRING	Description of the camera model.

Sample

local str = Image.Calibration.CameraModel.toString(cameraModel)

Image.Calibration.Correction

Short description

Correction of image distortions based on a calibrated camera model. Supports correction of lens distortion and perspective distortion from small tilt angles and image rotations.

Keywords

distortion, lens, perspective, rectification, rectify, untilt, unwarp, undistort

Overview

apply(), create(), getValidRegion(), getVirtualCamera(), mapPoints(), setAlignMode(), setUndistortMode(), setUntiltMode()

Functions

apply()

Short description

Apply the image correction to an input image.

Parameters
Name	Type	Description
corr	HANDLE	The correction object to use.
inputImage	CONST_OBJECT Image	Input image

Return values
Name	Type	Description
outputImage	OBJECT Image	Output image.

Sample

outputImage = corr:apply(inputImage)

create()

Short description

Create an image correction object.

Return values
Name	Type	Description
corr	HANDLE

Sample

corr = Image.Calibration.Correction.create()

getValidRegion()

Short description

Get a pixel region corresponding to the valid part of the corrected image. The valid part of the output image contains pixel values from the input image, and the invalid part is just set to zero.

Parameters
Name	Type	Description
corr	HANDLE	The correction object to use.

Return values
Name	Type	Description
validRegion	OBJECT Image.PixelRegion	Valid region of the output.

Sample

validRegion = corr:getValidRegion()

getVirtualCamera()

Short description

Get a camera model representing the virtual camera producing the corrected image.

Parameters
Name	Type	Description
corr	HANDLE	The correction object to use.

Return values
Name	Type	Description
camera	OBJECT Image.Calibration.CameraModel	Virtual camera of the correction procedure.

Sample

camera = corr:getVirtualCamera()

mapPoints()

Short description

Map points between the four coordinate systems related to the correction process. See the CoordinateSystem enum for details.

Parameters
Name	Type	Description
corr	HANDLE	The correction object to use.
pointsIn	OBJECT Point	Points to transform (single point or array).
sourceSystem	ENUM CoordinateSystem	Specifies the coordinate system in which the input point is defined.
targetSystem	ENUM CoordinateSystem	Specifies the coordinate system to transform the points into.

Return values
Name	Type	Description
pointsOut	OBJECT Point	Transformed points (single point or array).

Sample

pointsOut = corr:mapPoints(pointsIn, sourceSystem, targetSystem)

setAlignMode()

Short description

Setup the correction to map specific world ground plane rectangle to an image. This gives precise control of the pixel size and world origin of the output image.

Parameters
Name	Type	Description
corr	HANDLE	The correction object to setup.
cameraModel	OBJECT Image.Calibration.CameraModel	A model of a calibrated camera, as returned from the Image.Calibration functions.
worldRect	CONST_OBJECT Shape	World rectangle describing the world region to cover.
pixelSize	FLOAT	Desired pixel size (mm/pixel) of the output image. If omitted, a similar pixel size as in the input image center will be used.
interpolation	ENUM InterpolationMethod	Interpolation method to use. Default is LINEAR.

Sample

corr:setAlignMode(cameraModel, worldRect, pixelSize, interpolation)

setUndistortMode()

Short description

Setup the correction to compensate for lens distortion only. The other parts of the camera model are ignored.

Parameters
Name	Type	Description
corr	HANDLE	The correction object to setup.
cameraModel	CONST_OBJECT Image.Calibration.CameraModel	A model of a calibrated camera, as returned from the Image.Calibration functions.
cropMode	ENUM CorrectionCropMode	Crop mode, determines how to crop the output. Default is FULL.
interpolation	ENUM InterpolationMethod	Interpolation method to use. Default is LINEAR.

Sample

corr:setUndistortMode(cameraModel, cropMode, interpolation)

setUntiltMode()

Short description

Setup the correction to compensate for lens distortion and perspective distortions caused by a tilt angle between the world ground plane and the camera. Any in-plane rotation between the camera and world is left unaltered.

Parameters
Name	Type	Description
corr	HANDLE	The correction object to setup.
cameraModel	CONST_OBJECT Image.Calibration.CameraModel	A model of a calibrated camera, as returned from the Image.Calibration functions.
cropMode	ENUM CorrectionCropMode	Crop mode, determines how to crop the output. Default is FULL.
interpolation	ENUM InterpolationMethod	Interpolation method to use. Default is LINEAR.
targetWidth	INT	Output image width. Default is same size as the input.
targetHeight	INT	Output image height. Default is same size as the input.

Sample

corr:setUntiltMode(cameraModel, pixelSize, origin)

Image.Fixture

Short description

Helper object for transformation of geometrical primitives between different views of the same object. This object is typically used in a locate-inspect concept, where a teach image is used to define a set of measurement tasks. These measurement tasks will then be executed on a set of live images, where the object to measure may be translated, rotated and/or scaled differently than in the teach image. Typically, the following steps are included in locate-inspect applications: - Teach a matching algorithm (EdgeMatcher, PointMatcher, PatternMatcher) from a teach image. Use the teach pose returned from the teach procedure as reference pose for the fixture. - Define a set of points or shapes in the teach image, related to various measurement tasks. Append these to the fixture using the append functions. - For each live image, find the object using a match call of the selected matching algorithm. Transform the fixture to this new object pose using Fixture.transform. - Get the transformed points or shapes using the get functions, now relating to the found pose of the object in the live image. Saving and loading a fixture: A Image.Fixture instance can be saved and loaded (serialized/deserialized) using the Object.save() and Object.load() functions.

Keywords

local, object, reference, coordinate system

Overview

appendAngle(), appendPoint(), appendPose(), appendShape(), create(), getAngle(), getAsPixelRegion(), getPoint(), getPose(), getShape(), setReferencePose(), toString(), transform()

Functions

appendAngle()

Short description

Append an angle to the fixture.

Parameters
Name	Type	Description
fixture	HANDLE	Fixture object.
name	STRING	Name of the angle, used when retrieving the angle later on.
angle	FLOAT	Angle to append.

Sample

Image.Fixture.appendAngle(fixture, "angle1", 3.1415/2)

appendPoint()

Short description

Append a point to the fixture.

Parameters
Name	Type	Description
fixture	HANDLE	Fixture object.
name	STRING	Name of the point, used when retrieving the point later on.
point	CONST_OBJECT Point	Point to append.

Sample

Image.Fixture.appendPoint(fixture, "point1", point)

appendPose()

Short description

Append a pose transform to the fixture. Typically, the appended pose defines the pose of an object part. For example, the pose returned from the PatternVerifier teach method can be appended to a fixture. After calling Fixture.transform() to transform the fixture to a live image, Fixture.getPose() will give the pose of the part in the live image. The output from getPose can then be used in a call to PatternVerifier.verify() to verify the part in the live image.

Parameters
Name	Type	Description
fixture	HANDLE	Fixture object.
name	STRING	Name of the pose, used when retrieving the pose later on.
pose	CONST_OBJECT Transform	Pose to append, defined in image world coordinates.

Sample

Image.Fixture.appendPose(fixture, "pose1", pose)

appendShape()

Short description

Append a shape or composite shape to the fixture.

Parameters
Name	Type	Description
fixture	HANDLE	Fixture object.
name	STRING	Name of the shape, used when retrieving the shape later on.
shape	CONST_OBJECT Shape	Shape or composite shape to append.

Sample

Image.Fixture.appendShape(fixture, "shape1", shape)

create()

Short description

Create a new fixture.

Return values
Name	Type	Description
fixture	HANDLE	The new fixture.

Sample

fixture = Image.Fixture.create()

getAngle()

Short description

Get an angle from the fixture, transformed according to the current fixture transform.

Parameters
Name	Type	Description
fixture	HANDLE	Fixture object.
name	STRING	Name of the angle to retrieve.

Return values
Name	Type	Description
angle	FLOAT	The retrieved angle.

Sample

angle = Image.Fixture.getAngle(fixture, "angle1")

getAsPixelRegion()

Short description

Get a shape or composite shape region from the fixture, transformed directly to a pixel region for use as algorithm input. Since the returned object is not a shape, more general transformations are supported by this function compared to getShape().

Parameters
Name	Type	Description
fixture	HANDLE	Fixture object.
name	STRING	Name of the shape or composite shape to retrieve.
referenceImage	CONST_OBJECT Image	Reference image, use to determine the pixel-world mapping.

Return values
Name	Type	Description
region	OBJECT Image.PixelRegion	The transformed shape, converted to a pixel region.

Sample

region = Image.Fixture.getAsPixelRegion(fixture, "shape1", referenceImage)

getPoint()

Short description

Get a point from the fixture, transformed according to the current fixture transform.

Parameters
Name	Type	Description
fixture	HANDLE	Fixture object.
name	STRING	Name of the point to retrieve.

Return values
Name	Type	Description
point	OBJECT Point	The retrieved point.

Sample

point = Image.Fixture.getPoint(fixture, "point1")

getPose()

Short description

Get a pose from the fixture, transformed according to the current fixture transform. Typically, this is used to get the pose of an object part. For example, the pose returned from getPose can be used as input to the PatternVerifier match function. See appendPose for more information.

Parameters
Name	Type	Description
fixture	HANDLE	Fixture object.
name	STRING	Name of the pose to retrieve.

Return values
Name	Type	Description
pose	OBJECT Transform	The retrieved pose.

Sample

pose = Image.Fixture.getPose(fixture, "pose1")

getShape()

Short description

Get a shape or composite shape from the fixture, transformed according to the current fixture transform. Nil is returned if the shape can not be transformed accordingly.

Parameters
Name	Type	Description
fixture	HANDLE	Fixture object.
name	STRING	Name of the object to retrieve.

Return values
Name	Type	Description
shape	AUTO	The retrieved shape or composite shape.

Sample

shape = Image.Fixture.getShape(fixture, "shape1")

setReferencePose()

Short description

Set the reference pose of this fixture. This defines the object pose that all geometrical items will be related to. Typically, the teachPose output from the teach function of a matching tool (for example Image.Matching.EdgeMatcher.teach()) is used as input to this function.

Parameters
Name	Type	Description
fixture	HANDLE	Fixture object.
referencePose	CONST_OBJECT Transform	Pose transform of the object that all appended geometrical items will be related to.

Sample

Image.Fixture.setReferencePose(fixture, referencePose)

toString()

Short description

Get a user-friendly string description of the fixture.

Parameters
Name	Type	Description
fixture	HANDLE	Fixture object.

Return values
Name	Type	Description
description	STRING	User-friendly description of the fixture.

Sample

local description = Image.Fixture.toString(fixture)

transform()

Short description

Transform the fixture to a new pose. This will affect the pose of all geometrical items retrieved using the get functions. Typically, the pose transform output from the match function of a matching tool (for example Image.Matching.EdgeMatcher.match()) is often used as input to this function.

Parameters
Name	Type	Description
fixture	HANDLE	Fixture object.
poseTransform	CONST_OBJECT Transform	Pose transform of the new fixture pose.

Sample

Image.Fixture.transform(fixture, poseTransform)

Image.Fixture3D

Short description

Helper object for transformation of 3D geometrical primitives (Shapes, Points, regions). This object is typically used in a locate-inspect concept together with the EdgeMatcher3D, where a teach image is used to define a set of measurement tasks. These measurement tasks will then be executed on a set of live images, where the object to measure may be translated, rotated and/or scaled differently than in the teach image. The shadow region of a shape on the z=0 plane can be obtained directly using getAsPixelRegion. This function also allows more general transforms compared to the getShape function. E.g. using getPose on a circle will only allow up to similarity transforms, while getAsPixelRegion allows homography transforms. Typically, the following steps are included in locate-inspect applications: - Teach a 3D matching algorithm such as EdgeMatcher3D using a teach image. Use the teach pose returned from the teach procedure as reference pose for the fixture. - Define a set of points or shapes in the teach image, related to various measurement tasks. Append these to the fixture using the append functions. - For each live image, find the object using a match call of the selected matching algorithm. Transform the fixture to this new object pose using Fixture3D.transform(). - Get the transformed points or shapes using the get functions, now relating to the found pose of the object in the live image. Saving and loading a fixture: A Image.Fixture3D instance can be saved and loaded (serialized/deserialized) using the Object.save() and Object.load() functions.

Keywords

local, object, reference, coordinate system

Overview

appendPoint(), appendPose(), appendShape(), create(), getAsPixelRegion(), getPoint(), getPose(), getShape(), setReferencePose(), toString(), transform()

Functions

appendPoint()

Short description

Appends a 3D point to the fixture.

Parameters
Name	Type	Description
fixture	HANDLE	Fixture object.
name	STRING	Name of the point, used when retrieving the point later on.
point	CONST_OBJECT Point	3D point to append.

Sample

Image.Fixture3D.appendPoint(fixture, "point1", point)

appendPose()

Short description

Appends a pose transform (Transform 3D object) to the fixture. Typically, the appended pose defines the pose of an object part, for example, the pose returned from teaching 3D matchers for sub-components. After calling Fixture3D.transform() to transform the fixture to a live image, Fixture3D.getPose() will give the pose of the part in the live image.

Parameters
Name	Type	Description
fixture	HANDLE	Fixture object.
name	STRING	Name of the pose, used when retrieving the pose later on.
pose	CONST_OBJECT Transform	Transform pose (3D Transform) to append, defined in image world coordinates.

Sample

Image.Fixture3D.appendPose(fixture, "pose1", pose)

appendShape()

Short description

Appends a Shape3D object to the fixture.

Parameters
Name	Type	Description
fixture	HANDLE	Fixture object.
name	STRING	Name of the shape, used when retrieving the shape later on.
shape	CONST_OBJECT Shape3D	Shape3D object to append.

Sample

Image.Fixture3D.appendShape(fixture, "shape1", shape)

create()

Short description

Creates a new 3D fixture.

Return values
Name	Type	Description
fixture	HANDLE	The new fixture.

Sample

fixture = Image.Fixture3D.create()

getAsPixelRegion()

Short description

Gets a 3D shape from the fixture represented as a pixel region plus height boundaries (zMin, zMax). The pixel region is the convex hull of the shape projected onto the plane z = 0. More general transforms are allowed when using getAsPixelRegion, even transforms that changes the type of shape.

Parameters
Name	Type	Description
fixture	HANDLE	Fixture object.
name	STRING	Name of the shape to retrieve.
referenceImage	CONST_OBJECT Image	Reference image, used to supply the image world coordinate system.

Return values
Name	Type	Description
region	OBJECT Image.PixelRegion	The transformed shape, converted to a pixel region.
zMin	FLOAT	The lowest z-value encountered in the shape after transformation but before projection.
zMax	FLOAT	The highest z-value encountered in the shape after transformation but before projection.

Sample

region = Image.Fixture3D.getAsPixelRegion(fixture, "shape1", referenceImage)

getPoint()

Short description

Gets a point from the fixture, transformed according to the current fixture transform.

Parameters
Name	Type	Description
fixture	HANDLE	Fixture object.
name	STRING	Name of the point to retrieve.

Return values
Name	Type	Description
point	OBJECT Point	The retrieved 3D point.

Sample

point = Image.Fixture3D.getPoint(fixture, "point1")

getPose()

Short description

Gets a pose from the fixture, transformed according to the current fixture transform. Typically, this is used to get the pose of an object part.

Parameters
Name	Type	Description
fixture	HANDLE	Fixture object.
name	STRING	Name of the pose to retrieve.

Return values
Name	Type	Description
pose	OBJECT Transform	The retrieved pose transform (Transform 3D).

Sample

pose = Image.Fixture3D.getPose(fixture, "pose1")

getShape()

Short description

Gets a shape from the fixture, transformed according to the current fixture transform.

Parameters
Name	Type	Description
fixture	HANDLE	Fixture object.
name	STRING	Name of the shape to retrieve.

Return values
Name	Type	Description
shape	OBJECT Shape3D	The retrieved 3D shape.

Sample

shape = Image.Fixture3D.getShape(fixture, "shape1")

setReferencePose()

Short description

Sets the reference pose of this fixture. This defines the object pose that all geometrical items will be related to. Typically, the teachPose output from the teach function of a matching tool, e.g., EdgeMatcher3D, is used as input to this function.

Parameters
Name	Type	Description
fixture	HANDLE	Fixture object.
referencePose	CONST_OBJECT Transform	Pose transform (Transform3D) of the object that all appended geometrical items will be related to.

Sample

Image.Fixture3D.setReferencePose(fixture, referencePose)

toString()

Short description

Gets a user-friendly string description of the fixture.

Parameters
Name	Type	Description
fixture	HANDLE	Fixture object.

Return values
Name	Type	Description
description	STRING	User-friendly description of the fixture.

Sample

local description = Image.Fixture3D.toString(fixture)

transform()

Short description

Transforms the fixture to a new pose. This will affect the pose of all geometrical items retrieved using the get functions. Typically, the pose transform output from the match function of a matching tool is often used as input to this function.

Parameters
Name	Type	Description
fixture	HANDLE	Fixture object.
poseTransform	CONST_OBJECT Transform	Pose transform (Transform 3D object) of the new fixture pose.

Sample

Image.Fixture3D.transform(fixture, poseTransform)

Image.Format

Short description

Image file formats/encodings.

Overview

Image.Format.BMP

Short description

BMP encoding functionality

Overview

create(), decode(), encode()

Functions

create()

Short description

Creates a new instance of the BMP encoder.

Return values
Name	Type	Description
handle	HANDLE	Handle to the instance.

Sample

local handle = Image.Format.BMP.create()

decode()

Short description

Create an Image object from a binary buffer containing a BMP encoded image.

Parameters
Name	Type	Description
handle	HANDLE	Handle to the BMP instance
bmpBuffer	BINARY	Binary buffer containing the BMP encoded image

Return values
Name	Type	Description
image	OBJECT Image	Decoded image or nil

Sample

local image = Image.Format.BMP.decode(handle, bmpBuffer)

encode()

Short description

Create a binary buffer with the BMP encoded image data. Supported image types: UINT8, RGB24

Parameters
Name	Type	Description
handle	HANDLE	Handle to the instance
imageIn	CONST_OBJECT Image	image to encode

Return values
Name	Type	Description
bmpBuffer	BINARY	binary buffer containing the BMP encoded image or nil

Sample

local bmpBuffer = Image.Format.BMP.encode(handle, image)

Image.Format.JPEG

Short description

JPEG encoding functionality

Overview

create(), decode(), encode(), setQuality()

Functions

create()

Short description

Creates a new instance of the JPEG encoder. Default quality level is 50.

Return values
Name	Type	Description
handle	HANDLE	Handle to the new instance if available. Can be nil if unavailable.

Sample

local handle = Image.Format.JPEG.create()

decode()

Short description

Create an Image object from a binary buffer containing a JPEG encoded image.

Parameters
Name	Type	Description
handle	HANDLE	Handle to the JPEG instance
jpegBuffer	BINARY	Binary buffer containing the JPEG encoded image

Return values
Name	Type	Description
image	OBJECT Image	Decoded image or nil

Sample

local image = Image.Format.JPEG.decode(handle, jpegBuffer)

encode()

Short description

Create a binary buffer with the JPEG encoded image data.

Parameters
Name	Type	Description
handle	HANDLE	Handle to the JPEG instance
imageIn	CONST_OBJECT Image	Image to encode

Return values
Name	Type	Description
jpegBuffer	BINARY	Binary buffer containing the JPEG encoded image or nil

Sample

local jpegBuffer = Image.Format.JPEG.encode(handle, image)

setQuality()

Short description

Configure the JPEG encoding quality, a lower value results in higher compression.

Parameters
Name	Type	Description
handle	HANDLE	Handle to the JPEG instance
quality	INT	The minimum/maximum values depend on the underlying implementation.

Return values
Name	Type	Description
success	BOOL	True if successful, false otherwise

Sample

local success = Image.Format.JPEG.setQuality(handle, 50)

Image.Format.PNG

Short description

PNG encoding functionality

Overview

create(), decode(), encode(), setCompression()

Functions

create()

Short description

Creates a new instance of the PNG encoder.

Return values
Name	Type	Description
handle	HANDLE	Handle to the instance.

Sample

local handle = Image.Format.PNG.create()

decode()

Short description

Create an Image object from a binary buffer containing a PNG encoded image.

Parameters
Name	Type	Description
handle	HANDLE	Handle to the PNG instance
pngBuffer	BINARY	Binary buffer containing the PNG encoded image

Return values
Name	Type	Description
image	OBJECT Image	Decoded image or nil

Sample

local image = Image.Format.PNG.decode(handle, pngBuffer)

encode()

Short description

Create a binary buffer with the PNG encoded image data. Supported image types: UINT8, UINT16, RGB24

Parameters
Name	Type	Description
handle	HANDLE	Handle to the instance
imageIn	CONST_OBJECT Image	image to encode

Return values
Name	Type	Description
pngBuffer	BINARY	binary buffer containing the PNG encoded image or nil

Sample

local pngBuffer = Image.Format.PNG.encode(handle, image)

setCompression()

Short description

Configure the PNG encoding compression (0-9), a higher value results in higher compression and higher run time.

Parameters
Name	Type	Description
handle	HANDLE	Handle to the PNG instance
compression	INT	Ranges from 0 (no compression) to 9 (high compression). Default: 6.

Return values
Name	Type	Description
success	BOOL	True if successful, false otherwise

Sample

local success = Image.Format.PNG.setCompression(handle, 1)

Image.Matching

Short description

Functions for matching and locating objects and patterns in images based on different object models, including edge-based models, interest point models and pixel pattern models.

Image.Matching.EdgeMatcher

Short description

Object matching of objects which are well defined by clean edges/contours in a 2D image. An alternative to the EdgeMatcher is the PointMatcher for objects whose appearance is rather described by a texture pattern. Teach an object model from a reference image and call match to find the location of the same object in a new image. The EdgeMatcher searches for translation, rotation and scale (range 80% - 120%) of objects. Results are given as pose transforms which describe how the object model is transformed to matched positions in the new image. Each match gets a score between 0.0 and 1.0 where 1.0 means a perfect match. The EdgeMatcher is often used together with the Image.Fixture object that facilitates local coordinate transforms based on the result of the EdgeMatcher. The most important parameters for the EdgeMatcher are the following: - Edge threshold: Make sure to select an edge strength threshold that includes the edges of the reference object but excludes clutter edges in the background. Use the getModelContours() function to graphically verify the object model obtained. - Background clutter: If the images contain other patterns and structures other than the object of interest, use the HIGH setting in setBackgroundClutter() which is the default. If the object is on a clean background one can gain speed by setting the background clutter flag to MEDIUM or LOW. There is an interaction with the background clutter setting and the downsample factor parameter below though: It can be possible to run with higher downsample factors using the HIGH background clutter and thus gain higher speed compared to runnning a MEDIUM background clutter and a lower downsample factor. - Downsample factor: The EdgeMatcher works internally on downsampled images for computational performance reasons. The downsample factor is the most important parameter for the speed versus robustness trade-off. A initial choice of downsample factor could be one that generates a downsampled image of size about 200 x 200. For example, if images of size 1024 x 1024 are used, one could start experimenting with a downsample factor of 5. The downsample factor has an effect on the robustness of the algorithm (finding the correct match) but not on the position accuracy. - Rotation range: The rotation range parameter should be selected to be as narrow as possible both for computational reasons and for robustness reasons. If it is known that the target object only can appear within a certain rotation interval relative to the teach pose, make sure to reduce the rotation range search parameter. - Scale range: As with the rotation range parameter, set the scale range as narrowly as possible for computational and performance reasons. Pixel types: The EdgeMatcher accepts uint8 and uint16 pixel type images. Hardware acceleration: Some devices have FPGA-support for the EdgeMatcher. It is possible to switch between the CPU and FPGA versions using the setProcessingUnit()-function. If there is FPGA support it is set as default, but note that the FPGA is not able to support all configurations, mainly there is a lower restriction on the downsample factor for memory limitation reasons. There is typically only one instance of the FPGA calculation unit in a device. If many EdgeMatcher instances are created running in parallel, all using the FPGA acceleration, they may try to access the FPGA resource at the same time. The behavior is then that a match call will wait until the FPGA resource is available again. Image world coordinate system handling: The image (x,y)-pixelsize and origin are considered within the EdgeMatcher, all calculations are made in the image world coordinate system. The output pose transforms are also expressed in the image world coordinate system. Missing data handling: The EdgeMatcher does not accept missing data images, turn off the missing data flag to use it anyway or use the EdgeMatcher3D. Object model: An object representation of the contours in the teach reference image is generated in a teach call. The center of the model, and also the rotation center, is the center of the teach region. Saving and loading a configuration: A trained EdgeMatcher instance can be saved and loaded (serialized/deserialized) using the Object.save() and Object.load() functions.

Keywords

contour, find, matching, object, pattern, shape, locator

Overview

create(), getDownsampleFactorLimits(), getEdgePoints(), getModelContours(), getModelPoints(), getTeachPose(), match(), setBackgroundClutter(), setDownsampleFactor(), setEdgeThreshold(), setMaxMatches(), setMinSeparation(), setProcessingUnit(), setRotationRange(), setScaleRange(), setTimeout(), teach(), toString()

Functions

create()

Short description

Creates a new edge matcher for object localization in 2D intensity images.

Return values
Name	Type	Description
matcher	HANDLE	The new EdgeMatcher instance.

Sample

locator = Image.Matching.EdgeMatcher.create()

getDownsampleFactorLimits()

Short description

A support function which outputs the minimum and maximum values of the downsample factor. In particular when FPGA acceleration is utilized there are memory limitations setting a minimal value for the downsample factor. The maximum downsample factor is derived from the minimum allowed downsampled image size to look for matches in.

Parameters
Name	Type	Description
matcher	HANDLE	The instance to use.
image	CONST_OBJECT Image	An image with the size that the EdgeMatcher will work on

Return values
Name	Type	Description
minDsf	FLOAT	Minimum allowed downsample factor.
maxDsf	FLOAT	Maximum allowed downsample factor.

Sample

minDsf, maxDsf = Image.Matching.EdgeMatcher.getDownsampleFactorLimits(matcher, image)

getEdgePoints()

Short description

Deprecated: This function has been renamed to getModelPoints to align with the PointMatcher API. The functions give the same output. Get sample edges of the object represented as a vector of 2D Points. This function is intended for graphical feedback using representative points on edges of the reference object. The points are returned in internal model coordinates and must be transformed using a pose transform to overlay them onto the teach or live image. Can only be called after a successful teach.

Parameters
Name	Type	Description
matcher	HANDLE	The matcher instance to use.

Return values
Name	Type	Description
points	OBJECT Point	Edge points in internal model coordinates.

Sample

points = Image.Matching.EdgeMatcher.getEdgePoints(matcher)

getModelContours()

Short description

Get object model contours for visualization purposes. Results are returned as polyline shape objects.

Parameters
Name	Type	Description
matcher	HANDLE	The matcher instance to use.

Return values
Name	Type	Description
polylines	OBJECT Shape	Edge lines in internal model coordinates.

Sample

polylines = Image.Matching.EdgeMatcher.getModelContours(matcher)

getModelPoints()

Short description

Get the object model as a vector of 2D Points of located edges. This function is intended for graphical feedback using representative points on edges of the reference object. The points are returned in internal model coordinates and must be transformed using a pose transform to overlay them onto the teach or live image. Can only be called after a successful teach. Note: As it may be inefficient to overlay a lot of points in images, it is recommended to use the getModelContours function instead for graphical feedback.

Parameters
Name	Type	Description
matcher	HANDLE	The matcher instance to use.
maxCount	INT	Optional parameter to specify the maximum number of control points along the polylines to return. Default is 500 and absolute max is 5000. Note that one can obtain fewer points than the value specified here.

Return values
Name	Type	Description
points	OBJECT Point	Edge points in internal model coordinates.

Sample

points = Image.Matching.EdgeMatcher.getModelPoints(matcher, 1000)

getTeachPose()

Short description

Returns the teach pose that was created and returned by the last teach call. If the last teach was unsuccessful, nil is returned.

See also

Image.Matching.EdgeMatcher.teach

Parameters
Name	Type	Description
matcher	HANDLE	The instance to use

Return values
Name	Type	Description
teachPose	OBJECT Transform	2D pose transform transforming the object model to its position in the teach image, or nil if unsuccessful.

Sample

teachPose = Image.Matching.EdgeMatcher.getTeachPose(matcher)

match()

Short description

Finds objects in an image by matching with the teach model. A teach call must be made first. The output is a vector of pose transforms, one transform for each found match. The transform describes how the object model is transformed to the match in the live image. For the EdgeMatcher, the output posed transforms are of 2D Transform type. They can be used with the Fixture object to transform other 2D objects and regions. The match scores are based on how well edge information in the image matches the object model. The status code indicates what happened during the call and may be set to any of the following values: * 0: Matching was successful (although no objects may have been found, there was no error). * 10: Logical error, e.g. missing parameters or parameters outside the permissible range, see the printed error message. * 90: Error not related to any of the other categories, see the printed error message. * 210: Timeout, matching was aborted. Check the set time limit. * 220: Image error, something was wrong with the input image, e.g. invalid, too small, unsupported type. * 230: Region error, something was wrong with the search region. * 240: Unteached matcher, the matcher is not successfully teached. * 260: FPGA error, something was wrong with the FPGA, e.g. too large image or the FPGA was busy.

Parameters
Name	Type	Description
matcher	HANDLE	The matcher instance to use
liveImage	CONST_OBJECT Image	The live image to find the object in.
searchRegion	CONST_AUTO	Optional search region in the live image, either a pixel region or a closed 2D shape such as a rectangle. Edges are only detected within this region and it should cover the entire object to be found.

Return values
Name	Type	Description
poseTransforms	OBJECT Transform	Pose transforms defining the location of each detected object.
matchScores	FLOAT	A score between 0.0 and 1.0 for each detected object (high score means good match).
status	INT	A status code indicating what happened during the call.

Sample

transforms, scores, status = Image.Matching.EdgeMatcher.match(matcher, liveImage, searchRegion, priorRotation, priorScale)

setBackgroundClutter()

Short description

A setting that indicates to what level the live images supplied to the match function are expected to contain non-object edges. Keep this parameter at HIGH (default) if the image contains a lot of other edges, structures, noise, clutter in areas not belonging to the object of interest. Examples of such structures are barcodes and text which generate a lot of edge responses. For clean scenes this parameter can be set to MEDIUM or LOW to gain speed. Note however that it may be possible to work with higher downsample factors if this parameter is set to HIGH. Setting this parameter will invalidate any previous teach call.

Parameters
Name	Type	Description
matcher	HANDLE	The instance to use.
backgroundClutterLevel	AUTO	Set to the expected background clutter level, LOW, MEDIUM or HIGH. Default is HIGH. In a previous version of this function this input was a bool where 'true' maps to the MEDIUM enum and 'false' to the LOW enum.

Sample

Image.Matching.EdgeMatcher.setBackgroundClutter(matcher, backgroundClutterLevel)

setDownsampleFactor()

Short description

Sets downsampling factor in the x- and y-dimensions of the image. If the original image has size (M,N), the downsampled image has size (M/d, N/d) where d is the downsampling factor. More downsampling will increase the speed but eventually will reduce the matching robustness. Especially, for small object or thin contours the downsampling cannot be set too low as the details will become washed out in the downsampled image. However, some downsampling can also be beneficial for the matching as noise and irrelevant edges are removed. Therefore, a good downsampling is usually somewhere between 2.0 and 10.0. Setting a high downsampling does not have an impact on the final matching position accuracy as matches are fine-tuned on finer image resolutions. For FPGA acceleration there is lower limit on the downsampling factor due to memory limitations. This limit is different for various devices but is usually around 5.0 to 6.0. Use the getDownsampleFactorLimits to find out the lower and upper limits on the downsample factor.

Parameters
Name	Type	Description
matcher	HANDLE	The instance to use.
downsampleFactor	FLOAT	A factor larger than or equal to 1.0. The default value is 8.0.

Sample

Image.Matching.EdgeMatcher.setDownsampleFactor(matcher, 6.0)

setEdgeThreshold()

Short description

Sets the edge threshold, i.e., minimal edge strength. The edge strength is calculated as using a local image gradient filter so that smooth edges may generate weak edge responses. The default value is 50. For lower contrast edges one must reduce this value and for very sharp and high-contrast edges it should be raised. Check with the getModelContours() function the edges that are obtained. Setting this parameter will invalidate any previous teach call.

Parameters
Name	Type	Description
matcher	HANDLE	The instance to use.
threshold	FLOAT	Edge threshold. The default value is 50.

Sample

Image.Matching.EdgeMatcher.setEdgeThreshold(matcher, 20)

setMaxMatches()

Short description

Sets the maximum number of objects to find in a match call. Note that the actual number found can be smaller than this number. Increasing the number of matches to consider is also a way to control the number of match candidates considered within the algorithm. Thus, in cluttered scenes it may be possible to increase robustness to increase this parameter even if one knows that there is only one object present at the end. This parameter can be updated in a teached matcher without re-teaching.

Parameters
Name	Type	Description
matcher	HANDLE	The instance to use.
matchCount	INT	An integer larger than or equal to 1 specifying the maximum number of objects to find. The default value is 1.

Sample

Image.Matching.EdgeMatcher.setMaxMatches(matcher, 3)

setMinSeparation()

Short description

Sets the minimum separation between the centers of object matches. The unit is in image world units (typically millimeters) taking the image pixel size into account. For 2D images the pixel size is by default 1.0, in which case the value equals the separation in pixels. This parameter only has effect if the number of matches to find is larger than 1. This parameter can be updated in a teached matcher without re-teaching.

Parameters
Name	Type	Description
matcher	HANDLE	The instance to use.
minSeparation	FLOAT	The minimum separation between the centers of two objects in image world units. The default value is 50.

Sample

Image.Matching.EdgeMatcher.setMinSeparation(matcher, 100)

setProcessingUnit()

Short description

Sets processing unit for the calculations. Some devices support FPGA acceleration of the EdgeMatcher. If this is the case the FPGA acceleration is set as default when the EdgeMatcher object is created.

Parameters
Name	Type	Description
matcher	HANDLE	The instance to use.
processingUnit	ENUM EdgeMatcherProcessingUnit	Which type of processing unit to use. If there is FPGA support in the device it will be used as default, otherwise CPU.

Return values
Name	Type	Description
success	BOOL	True if processing unit choice was successfully set. False if the processing unit or configuration is not supported.

Sample

Image.Matching.EdgeMatcher.setProcessingUnit(matcher, "FPGA")

setRotationRange()

Short description

Sets rotation interval to search in relative to the teach orientation. Narrowing the rotation search range speeds up the matching considerably. The search range is given as an angle in radian units. The rotation range interval is plus/minus the specified angle. The default value is PI radians, i.e., equal to a full rotation of plus/minus 180 degrees. If prior orientation information is known, the prior rotation can be set to allow a more narrow search range. The final search range is then up to plus/minus the search range parameter starting from the prior rotation. These parameters can be updated in a teached matcher without re-teaching.

Parameters
Name	Type	Description
matcher	HANDLE	The instance to use.
rotationRad	FLOAT	Angle in radian units, the maximum deviation from the original object orientation to search for. The default value is PI (180 degrees), i.e., full rotation.
priorRotationRad	FLOAT	Optional prior orientation in radians. If specified, the orientation search range is centered around this orientation. Default is zero (i.e. same orientation as teach object).

Sample

Image.Matching.EdgeMatcher.setRotationRange(matcher, rotationRad, priorRotationRad)

setScaleRange()

Short description

Sets scale interval to search relative to the teach size. The end points are represented as scale factors. setScaleRange(0.8, 1.2) searches for objects appearing down to 20% smaller or larger than the teach object. Default is not to search in scale, i.e, scale range parameters [1.0, 1.0]. An optional prior scale can be set, this affects both the minimum and maximum scale (both limits are multiplied with the prior scale). The prior scale moves the entire scale search range and does not affect matching time. The prior scale accepts a larger range of values than the min and max scale parameters. If the object to find has a fixed non-unit scale relative to the teach object, or if prior information on the scale of the object is available, use the prior scale. The default value is 1.0. By setting both minScale and maxScale to 1.0, scale search is disabled but the prior scale parameter still has effect. These parameters can be updated in a teached matcher without re-teaching.

Parameters
Name	Type	Description
matcher	HANDLE	The instance to use.
minScale	FLOAT	The smallest scale factor to search for. Lower limit is 0.8. Default value is 1.0.
maxScale	FLOAT	The largest scale factor to search for. Upper limit is 1.2. Default value is 1.0.
priorScale	FLOAT	Optional prior scale factor. Set to the expected scale of the object to find, relative to the size of the teach object. E.g. 1.25 if the object to find is 25% larger than the teach object. Min: 0.1. Max: 10

Sample

Image.Matching.EdgeMatcher.setScaleRange(matcher, minScale, maxScale, priorScale)

setTimeout()

Short description

Abort the match call if the match time exceeds a user-defined number of seconds. The main purpose is to protect against excessively long execution times, the granularity does not allow exact abortion at the given timeout parameter.

Parameters
Name	Type	Description
matcher	HANDLE	The instance to use.
timeoutSeconds	FLOAT	Time in seconds after which the algorithm should abort. The default value is 5 seconds.

Sample

Image.Matching.EdgeMatcher.setTimeout(matcher, 2.0)

teach()

Short description

Teaches an object model from edges in an image. It is important to set the edge strength threshold properly for this to work. Graphical feedback from the teach process is obtained through the getModelContours function. The status code indicates what happened during the call and may be set to any of the following values: * 0: Teaching was successful. * 10: Logical error, e.g. missing parameters or parameters outside the permissible range, see the printed error message. * 90: Error not related to any of the other categories, see the printed error message. * 110: Timeout, teaching was aborted. Check the set time limit. * 120: Image error, something was wrong with the input image, e.g. invalid, too small, unsupported type. * 130: Region error, something was wrong with the teach region. * 160: FPGA error, something was wrong with the FPGA, e.g. too large image or the FPGA was busy. * 170: Model edge error, too few model edges were found. Check the edge threshold, the input image and that the teach region covers the object of interest.

Parameters
Name	Type	Description
matcher	HANDLE	The instance to use
teachImage	CONST_OBJECT Image	The teach image.
teachRegion	CONST_AUTO	A pixel region or a closed 2D shape defining which area to consider as containing object edges.

Return values
Name	Type	Description
teachPoseTransform	OBJECT Transform	Pose transform of the object model, or nil if unsuccessful.
status	INT	A status code indicating what happened during the call.

Sample

teachPoseTransform, status = Image.Matching.EdgeMatcher.teach(matcher, teachImage, teachRegion)

toString()

Short description

Returns a human readable description of the matcher, including parameters.

Parameters
Name	Type	Description
matcher	HANDLE	The instance to use

Return values
Name	Type	Description
description	STRING	A description of the matcher object, or nil on failure.

Sample

description = Image.Matching.EdgeMatcher.toString(matcher)

Image.Matching.EdgeMatcher3D

Short description

The EdgeMatcher3D is an extension of the EdgeMatcher for object matching in range images and heightmaps. See the EdgeMatcher documentation for information on the basic usage. The documentation below focuses on the extensions and differences to the EdgeMatcher. The most important additional parameters and difference for the EdgeMatcher3D are the following: - The EdgeMatcher3D additionally searches for height and tilt (rotation around the x- and y-axes) of objects. The function setFindTiltHeight() enables and disables these additional parameters in the search. Tilt and height estimation is turned on as default. Turn these off for increased speed and robustness if the objects of interest always have the same tilt or height. - As range images generally contain missing data pixels, there is a mandatory "reference height" parameter that is set using the setReferenceHeight(). The EdgeMatcher3D uses this parameter to replace missing data pixels internally. - The output of the EdgeMatcher3D are 3D pose transforms. These can be used together with the Fixture3D object for locate-inspect applications. - Teach and search regions have additional zMin and zMax parameters to specify limits along the z-dimension. Pixel types: The EdgeMatcher3D accepts uint16 pixel type images. Hardware acceleration: Some devices have FPGA-support for the EdgeMatcher3D. It is possible to switch between the CPU and FPGA versions using the setProcessingUnit()-function. If there is FPGA support it is set as default, but note that the FPGA is not able to support all configurations, mainly there is a lower restriction on the downsample factor for memory limitation reasons. There is typically only one instance of the FPGA calculation unit in a device. If many EdgeMatcher3D instances are created running in parallel, all using the FPGA acceleration, they may try to access the FPGA resource at the same time. The behavior is then that a match call will wait until the FPGA resource is available again. Image world coordinate system handling: All parameters (thresholds, zMin, zMax, reference height) use the z-origin and z-pixelsize. That is, the parameters are interpreted in world units, typically in millimeters. The output pose transforms are also expressed in the image world coordinate system. Missing data handling: Both images with and without missing data flag are accepted. If the input image has missing data, the reference height parameter must be set to handle missing data internally. Object model: An object representation of the contours in the teach reference image is generated in a teach call. The center of the model, and also the rotation center, is the center of the teach region. The center in the z-dimension is (zMin + zMax)/2. Saving and loading a configuration: The configuration of a trained EdgeMatcher handle instance can be saved and loaded (serialized/deserialized) using the Object.save() and Object.load() functions.

Functions

create()

Short description

Creates a new edge matcher for 3D object localization in range images.

Return values
Name	Type	Description
matcher	HANDLE	The new instance.

Sample

locator = Image.Matching.EdgeMatcher3D.create()

getDownsampleFactorLimits()

Short description

Parameters
Name	Type	Description
matcher	HANDLE	The instance to use.
image	CONST_OBJECT Image	An image with the size that the EdgeMatcher3D will work on.

Return values
Name	Type	Description
minDsf	FLOAT	Minimum allowed downsample factor.
maxDsf	FLOAT	Maximum allowed downsample factor.

Sample

minDsf, maxDsf = Image.Matching.EdgeMatcher3D.getDownsampleFactorLimits(matcher, image)

getModelContours()

Short description

Gets object model contours for visualization purposes. Results are returned as polyline Shape3D objects.

See also

Parameters
Name	Type	Description
matcher	HANDLE	The matcher instance to use.

Return values
Name	Type	Description
polylines	OBJECT Shape3D	Edge lines in internal model coordinates.

Sample

polylines = Image.Matching.EdgeMatcher3D.getModelContours(matcher)

getModelPlanePoints()

Short description

Gets object model points for visualization purposes. This function returns center points of planar patches.

See also

Parameters
Name	Type	Description
matcher	HANDLE	The matcher instance to use.
maxCount	INT	Optional parameter to specify the maximum number points to return. Default is 500 and absolute max is 5000. Note that one can obtain fewer points than the value specified here.

Return values
Name	Type	Description
planarPoints	OBJECT Point	Vector of 3D planar points in internal model coordinates.

Sample

planarPoints = Image.Matching.EdgeMatcher3D.getModelPlanePoints(matcher)

getModelPoints()

Short description

Gets object model points for visualization purposes. This function returns points along the edges of object. See also getModelContours.

Parameters
Name	Type	Description
matcher	HANDLE	The matcher instance to use.
maxCount	INT	Optional parameter to specify the maximum number points to return. Default is 500 and absolute max is 5000. Note that one can obtain fewer points than the value specified here.

Return values
Name	Type	Description
points	OBJECT Point	Edge points in internal model coordinates.

Sample

points = Image.Matching.EdgeMatcher3D.getModelPoints(matcher)

getTeachPose()

Short description

Returns the teach pose that was created and returned by the last teach call. If the last teach was unsuccessful, nil is returned.

See also

Parameters
Name	Type	Description
matcher	HANDLE	The instance to use

Return values
Name	Type	Description
teachPose	OBJECT Transform	Pose transform transforming the object model to its position in the teach image, or nil if unsuccessful.

Sample

teachPose = Image.Matching.EdgeMatcher3D.getTeachPose(matcher)

match()

Short description

Finds objects in an image by matching with the teach model. A teach call must be made first. The output is a vector of pose transforms, one transform for each found match. The transform describes how the object model is transformed to the match in the live image. For the EdgeMatcher3D, the output pose transforms are of 3D Transform type. They can be used with the Fixture3D object to transform other 3D objects and regions. The match scores are based on how well edge information in the image matches the object model. Currently, only (x,y) locations of edges are included in the score calculation, meaning that a mismatch in z-dimension can still give a high score. Image world coordinate system handling: The two parameters zMin and zMax specify the range interval of the teach region. The parameters are interpreted in image world units, typically millimeters, taking the z-origin and z-pixelsize of the input image into account. The status code indicates what happened during the call and may be set to any of the following values: * 0: Matching was successful (although no objects may have been found, there was no error). * 10: Logical error, e.g. missing parameters or parameters outside the permissible range, see the printed error message. * 90: Error not related to any of the other categories, see the printed error message. * 210: Timeout, matching was aborted. Check the set time limit. * 220: Image error, something was wrong with the input image, e.g. invalid, too small, unsupported type. * 230: Region error, something was wrong with the search region. * 240: Unteached matcher, the matcher is not successfully teached. * 250: Reference plane error, something was wrong with the reference height for missing data. * 260: FPGA error, something was wrong with the FPGA, e.g. too large image or the FPGA was busy.

See also

Image.Matching.PatternMatcher.teach

Parameters
Name	Type	Description
matcher	HANDLE	The matcher instance to use
liveImage	CONST_OBJECT Image	The live image to find the object in.
searchRegion	CONST_AUTO	Optional search region in the live image, either a pixel region or a closed 2D shape such as a rectangle. Edges are only detected within this region and it should cover the entire object to be found.
zMin	FLOAT	Optional minimum value for z heights in world units (millimeters). Only edges above this level are included as features for the matching. If not set, a large negative number is used as default.
zMax	FLOAT	Optional maximum value for z heights in world units (millimeters). Only edges below this level are included as features for the matching. If not set, a large positive number is used as default.

Return values
Name	Type	Description
poseTransforms	OBJECT Transform	Pose transforms defining the location of each detected object.
matchScores	FLOAT	A score between 0.0 and 1.0 for each detected object (high score means good match).
status	INT	A status code indicating what happened during the call.

Sample

transforms, scores = Image.Matching.EdgeMatcher3D.match(matcher, liveImage)

proposeReferenceHeight()

Short description

Tries to estimate a reference height using valid pixels outside the teach region. Use this function carefully as it can give inaccurate results, for example if the teach region covers only the object partially.

Parameters
Name	Type	Description
matcher	HANDLE	The instance to use
teachImage	CONST_OBJECT Image	The teach image.
teachRegion	CONST_AUTO	A pixel region or a closed 2D shape defining which area to consider as containing object edges.

Return values
Name	Type	Description
referenceHeight	FLOAT	An estimated reference height in image world units, typically millimeters.. Returns nil if height estimation fails.

Sample

referenceHeight = Image.Matching.EdgeMatcher3D.proposeReferenceHeight(matcher, teachImage, teachRegion)

setBackgroundClutter()

Short description

A setting that indicates to what level the live images supplied to the match function are expected to contain non-object edges, e.g., noise and other clutter structures. The default setting is "MEDIUM". For very cluttered scenes it is possible to use a "HIGH" setting. Setting this parameter will invalidate any previous teach call.

Parameters
Name	Type	Description
matcher	HANDLE	The instance to use.
backgroundClutterLevel	AUTO	Set to the expected background clutter level, LOW, MEDIUM or HIGH. Default is MEDIUM.

Sample

Image.Matching.EdgeMatcher3D.setBackgroundClutter(matcher, backgroundClutterLevel)

setDownsampleFactor()

Short description

Sets downsample factor in the x- and y-dimensions of the image. If the original image has size (M,N), the downsampled image has size (M/d, N/d) where d is the downsample factor. More downsampling will increase the speed but eventually will reduce the matching robustness. Especially, for small object or thin contours the downsampling cannot be set too low as the details will become washed out in the downsampled image. However, some downsampling can also be beneficial for the matching as noise and irrelevant edges are removed. Therefore, a good downsampling is usually somewhere between 2.0 and 10.0. Setting a high downsampling does not have an impact on the final matching position accuracy as matches are fine-tuned on finer image resolutions.

Parameters
Name	Type	Description
matcher	HANDLE	The instance to use.
downsampleFactor	FLOAT	A factor larger than or equal to 1.0. The default value is 8.0.

Sample

Image.Matching.EdgeMatcher3D.setDownsampleFactor(matcher, downsampleFactor)

setEdgeThreshold()

Short description

Sets the edge threshold, i.e., minimal edge strength. The edge strength is calculated as using a local image gradient filter so that smooth edges may generate weak edge responses. The default value is 10. Check with the getModelPoints() or the getModelContours() function the edges that are obtained. Setting this parameter will invalidate any previous teach call. Image world coordinate system handling: The edge threshold is interpreted in the image world coordinate system, i.e., typically in millimeters. The threshold is converted internally to a raw pixel value threshold using the z-origin and z-pixelsize of the image.

Parameters
Name	Type	Description
matcher	HANDLE	The instance to use.
threshold	FLOAT	Edge threshold interpreted in the image world coordinate system. The default value is 10 for EdgeMatcher3D.

Sample

Image.Matching.EdgeMatcher3D.setEdgeThreshold(matcher, threshold)

setFindTiltHeight()

Short description

Flags to find the tilt and/or height of objects relative to the teach pose. Depending on the application, one may for example know that the tilt and or height is always the same as for the teach object. If so, turn off the estimation of these parameters for increased speed and robustness. If tilt-search is on, height-search is turned on automatically. Setting this parameter will invalidate any previous teach call. The maximum tilt angle the algorithm can find is about 10 - 15 degrees relative to the teach pose, for higher tilts the algorithm may not match robustly.

Parameters
Name	Type	Description
matcher	HANDLE	The matcher instance to use.
findTilt	BOOL	Set to true to find tilt of matched objects. Default is true.
findHeight	BOOL	Set to true to find height of matched objects. Default is true.

Sample

Image.Matching.setFindTiltHeight(matcher, findTilt, findHeight)

setMaxMatches()

Short description

Sets the maximum number of objects to find in a match call. Note that the actual number found can be smaller than this number. This parameter can be updated in a teached matcher without re-teaching.

Parameters
Name	Type	Description
matcher	HANDLE	The instance to use.
matchCount	INT	An integer larger than or equal to 1 specifying the maximum number of objects to find. The default value is 1.

Sample

Image.Matching.EdgeMatcher3D.setMaxMatches(matcher, matchCount)

setMinSeparation()

Short description

Sets the minimum separation in the (x,y)-dimension between the centers of object matches. This parameter only has effect if the number of matches to find is larger than 1. This parameter can be updated in a teached matcher without re-teaching. Image world coordinate system handling: The unit is in image world units (typically millimeters) taking the image (x,y)-pixelsizes into account.

Parameters
Name	Type	Description
matcher	HANDLE	The instance to use.
minSeparation	FLOAT	The minimum separation between the centers of two objects in image world units. The default value is 50.

Sample

Image.Matching.EdgeMatcher3D.setMinSeparation(matcher, minSeparation)

setProcessingUnit()

Short description

Sets processing unit for the calculations. Some devices support FPGA acceleration of the EdgeMatcher3D. If this is the case the FPGA acceleration is set as default when the EdgeMatcher3D object is created.

Parameters
Name	Type	Description
matcher	HANDLE	The instance to use.
processingUnit	ENUM EdgeMatcherProcessingUnit	Which type of processing unit to use. If there is FPGA support in the device it will be used as default, otherwise CPU.

Return values
Name	Type	Description
success	BOOL	True if processing unit choice was successfully set. False if the chosen processing unit is not supported.

Sample

Image.Matching.EdgeMatcher3D.setProcessingUnit(matcher, "FPGA")

setReferenceHeight()

Short description

Sets a reference height for missing data handling. This value is used to replace missing data pixels within the algorithm. Use the height of the floor, belt or any other application-dependent height. Setting this parameter is mandatory if the input images have the missing data flag on. If missing data has been removed before calling the EdgeMatcher3D, this parameter has no effect. This parameter can be updated in a teached matcher without re-teaching. A suggested reference height can be obtained using the proposeReferenceHeight()-function. Image world coordinate system handling: The reference height is interpreted in the image world coordinate system, typically in millimeters, considering the z-origin and z-pixelsize of the image.

Parameters
Name	Type	Description
matcher	HANDLE	The matcher instance to use.
referenceHeight	FLOAT	Reference height specified in world units, e.g., millimeters.

Sample

Image.Matching.EdgeMatcher3D.setReferenceHeight(matcher, referenceHeight)

setRotationRange()

Short description

Sets rotation interval around the z-axis to search in relative to the teach orientation. Narrowing the rotation search range speeds up the matching considerably. The search range is given as an angle in radian units. The rotation range interval is plus/minus the specified angle. The default value is PI radians, i.e., equal to a full rotation of plus/minus 180 degrees. This parameter can be updated in a teached matcher without re-teaching.

Parameters
Name	Type	Description
matcher	HANDLE	The instance to use.
rotationRad	FLOAT	Angle in radian units, the maximum deviation from the original object orientation to search for. The default value is PI.

Sample

Image.Matching.EdgeMatcher3D.setRotationRange(matcher, rotationRad)

setTimeout()

Short description

Parameters
Name	Type	Description
matcher	HANDLE	The instance to use.
timeoutSeconds	FLOAT	Time in seconds after which the algorithm should abort. The default value is 5 seconds.

Sample

Image.Matching.EdgeMatcher3D.setTimeout(matcher, timeoutSeconds)

teach()

Short description

Teaches an object model from edges in an image. It is important to set the edge strength threshold properly for this to work. Graphical feedback from the teach process is obtained through the getModelPoints() or getModelContours() functions. The teach procedure extracts both edge information and planar patches within the teach region. The latter are used to estimate tilt and height parameters in match. Image world coordinate system handling: The two parameters zMin and zMax specify the range interval of the teach region. The parameters are interpreted in image world units, typically millimeters, taking the z-origin and z-pixelsize of the input image into account. The status code indicates what happened during the call and may be set to any of the following values: * 0: Teaching was successful. * 10: Logical error, e.g. missing parameters or parameters outside the permissible range, see the printed error message. * 90: Error not related to any of the other categories, see the printed error message. * 110: Timeout, teaching was aborted. Check the set time limit. * 120: Image error, something was wrong with the input image, e.g. invalid, too small, unsupported type. * 130: Region error, something was wrong with the teach region. * 150: Reference plane error, something was wrong with the reference height for missing data. * 160: FPGA error, something was wrong with the FPGA, e.g. too large image or the FPGA was busy. * 170: Model edge error, too few model edges were found. Check the edge threshold, the input image and that the teach region covers the object of interest. * 180: Model plane error, too few planar probes were found. See status code 170.

Parameters
Name	Type	Description
matcher	HANDLE	The instance to use
teachImage	CONST_OBJECT Image	The teach image.
teachRegion	CONST_AUTO	A pixel region or a closed 2D shape defining which area to consider as containing object edges.
zMin	FLOAT	Optional minimum value for z heights in world units (millimeters). Only edges and planar points above this level are included in the model. If not set, a large negative number is used as default.
zMax	FLOAT	Optional maximum value for z heights in world units (millimeters). Only edges and planar points below this level are included in the model. If not set, a large positive number is used as default.

Return values
Name	Type	Description
teachPoseTransform	OBJECT Transform	Pose transform of the object model, or nil if unsuccessful.
status	INT	A status code indicating what happened during the call.

Sample

teachPoseTransform, status = Image.Matching.EdgeMatcher3D.teach(matcher, teachImage, teachRegion)

toString()

Short description

Returns a human readable description of the matcher, including parameters.

Parameters
Name	Type	Description
matcher	HANDLE	The instance to use

Return values
Name	Type	Description
description	STRING	A description of the matcher object.

Sample

description = Image.Matching.EdgeMatcher3D.toString(matcher)

Image.Matching.PatternMatcher

Short description

Finds an object in an image based on its pixel pattern. Teach the object from a reference image and call match to find the location of the same object in a live image. The PatternMatcher primarily searches for translated and rotated objects. Search in scale can be activated. Results are given in pose transforms which describe how the object model is transformed to matched positions in the live image. Each match gets a score between 0.0 and 1.0 where 1.0 means a perfect match. The PatternMatcher is often used together with the Fixture object that facilitates local coordinate transforms based on the result of the PatternMatcher. The most important parameters for the PatternMatcher are the following: - Downsample factor: The PatternMatcher works internally on downsampled images for computational performance reasons. The downsample factor is the most important parameter for the speed versus robustness trade-off. A initial choice of downsample factor could be one that generates a downsampled image of size about 150 x 150. That is, if images of size 1024 x 1024 are used, one could start experimenting with a downsample factor of around 7. A warning will be issued during teach if the downsample factor makes the object model too small. - Rotation range: The rotation range parameter should be selected to be as narrow as possible both for computational reasons and for robustness reasons. If it is known that the target object only can appear within a certain rotation interval, make sure to reduce the rotation range search parameter.

Keywords

correlation, matching, pixel, template, locator

Overview

create(), getDownsampleFactor(), getMaxMatches(), getMinSeparation(), getModelBoundingBox(), getRotationRange(), getTeachPose(), getTimeout(), match(), setDownsampleFactor(), setEdgeSensitivity(), setMaxMatches(), setMinSeparation(), setRotationRange(), setScaleSearch(), setTimeout(), teach(), toString()

Functions

create()

Short description

Creates a new pattern matcher for 2D object localization.

Return values
Name	Type	Description
locator	HANDLE	The new instance.

Sample

locator = Image.Matching.PatternMatcher.create()

getDownsampleFactor()

Short description

Gets the current downsample parameter setting.

Parameters
Name	Type	Description
locator	HANDLE	The instance to use.

Return values
Name	Type	Description
downsampleFactor	FLOAT	The current downsample factor.

Sample

downsampleFactor = Image.Matching.PatternMatcher.getDownsampleFactor(locator)

getMaxMatches()

Short description

Gets the current maximum number of objects to find.

Parameters
Name	Type	Description
locator	HANDLE	The instance to use.

Return values
Name	Type	Description
matchCount	INT	The current maximum number of objects to find.

Sample

matchCount = Image.Matching.PatternMatcher.getMaxMatches(locator)

getMinSeparation()

Short description

Gets the current minimum separation between centers of object matches.

Parameters
Name	Type	Description
locator	HANDLE	The instance to use.

Return values
Name	Type	Description
minSeparation	FLOAT	The minimum separation between the centers of two objects in image world units.

Sample

minSeparation = Image.Matching.PatternMatcher.getMinSeparation(locator)

getModelBoundingBox()

Short description

Get a bounding box of the teach object centered on the image world origin. It can be transformed directly by the pose transformations obtained from match to visualize matching results.

Parameters
Name	Type	Description
locator	HANDLE	The instance to use.

Return values
Name	Type	Description
modelBox	OBJECT Shape	A rectangle Shape representing the bounding box of the teach region, or nil if unsuccessful.

Sample

modelBox = Image.Matching.PatternMatcher.getModelBoundingBox(locator)

getRotationRange()

Short description

Gets the current rotation range parameter.

Parameters
Name	Type	Description
locator	HANDLE	The instance to use.

Return values
Name	Type	Description
rotationRad	FLOAT	The current rotation range.

Sample

rotationRad = Image.Matching.PatternMatcher.getRotationRange(locator)

getTeachPose()

Short description

Returns the teach pose that was created and returned by the last teach call. If the last teach was unsuccessful, nil is returned.

Parameters
Name	Type	Description
matcher	HANDLE	The instance to use.

Return values
Name	Type	Description
teachPose	OBJECT Transform	Pose transform transforming the object model to its position in the teach image, or nil if unsuccessful.

Sample

teachPose = Image.Matching.PatternMatcher.getTeachPose(matcher)

getTimeout()

Short description

Gets the selected timeout for matching.

Parameters
Name	Type	Description
locator	HANDLE	The instance to use.

Return values
Name	Type	Description
timeoutSeconds	FLOAT	Time in seconds after which the algorithm will abort.

Sample

timeoutSeconds = Image.Matching.PatternMatcher.getTimeout(locator)

match()

Short description

See also

Parameters
Name	Type	Description
locator	HANDLE	The matcher instance to use.
liveImage	CONST_OBJECT Image	The live image to find the object in.
searchRegion	CONST_OBJECT Shape	Optional search region in the live image, must be a rectangle.

Return values
Name	Type	Description
poseTransforms	OBJECT Transform	Pose transforms defining the location of each detected object.
matchScores	FLOAT	A score between 0.0 and 1.0 for each detected object (high score means good match).

Sample

transforms, scores = Image.Matching.PatternMatcher.match(locator, liveImage)

setDownsampleFactor()

Short description

Sets the downsample factor. Increasing this value will reduce computation time, but also reduce accuracy.

Parameters
Name	Type	Description
locator	HANDLE	The instance to use.
downsampleFactor	FLOAT	A factor larger than or equal to 1.0. The default value is 16.

Sample

Image.Matching.PatternMatcher.setDownsampleFactor(locator, 10.0)

setEdgeSensitivity()

Short description

Sets sensitivity to edge pixel intensity values used when matching. Sharp edges generate large errors for noisy edge positions, setting a low sensitivity (default) reduces errors due to small edge position variations among objects and typically increases the performance of the matcher.

Parameters
Name	Type	Description
locator	HANDLE	The instance to use.
edgeSensitivity	ENUM EdgeSensitivity	Sensitivity to edge pixels (e.g.: LOW, HIGH).

Sample

Image.Matching.PatternMatcher.setEdgeSensitivity(locator, edgeSensitivity)

setMaxMatches()

Short description

Sets the maximum number of objects to find in a match call. The actual number of matches found can be smaller than this number. This parameter can be changed without re-teaching.

Parameters
Name	Type	Description
locator	HANDLE	The instance to use.
matchCount	INT	An integer larger or equal than 1 specifying the maximum number of object to find.

Sample

Image.Matching.PatternMatcher.setMaxMatches(locator, 3)

setMinSeparation()

Short description

Parameters
Name	Type	Description
locator	HANDLE	The instance to use.
minSeparation	FLOAT	The minimum separation between the centers of two objects in image world units. The default value is 50.

Sample

Image.Matching.PatternMatcher.setMinSeparation(locator, 50)

setRotationRange()

Short description

Sets the rotation interval to search in, relative to the teach orientation. Narrowing the rotation search range speeds up the matching considerably. The search range is given as an angle in radian units. The rotation range interval is plus/minus the specified angle.

Parameters
Name	Type	Description
locator	HANDLE	The instance to use.
rotationRad	FLOAT	Angle in radian units, the maximum deviation from the original object orientation to search for. The default value is PI/16.

Sample

Image.Matching.PatternMatcher.setRotationRange(locator, 3.1415/16)

setScaleSearch()

Short description

Activates searching for objects of different scales, from minimalSize to maximalSize. By default, no scale search is active, corresponding to setScaleSearch(1.0, 1.0).

Parameters
Name	Type	Description
locator	HANDLE	The instance to use
minimalScale	FLOAT	Size of objects relative to teach object, 0.5 searches for objects down to half the size of the teach object.
maximalScale	FLOAT	Size of objects relative to teach object, 2.0 searches for objects up to double the size of the teach object.

Sample

Image.Matching.PatternMatcher.setScaleSearch(locator, minimalScale, maximalScale)

setTimeout()

Short description

Abort the match call if the match time exceeds a user-defined number of seconds. The default value is 5 seconds. This parameter can be changed without re-teaching.

Parameters
Name	Type	Description
locator	HANDLE	The instance to use.
timeoutSeconds	FLOAT	Time in seconds after which the algorithm should abort.

Sample

Image.Matching.PatternMatcher.setTimeout(locator, 10.0)

teach()

Short description

Teaches an object model from an image. It is important to set a reasonable downsample factor and the desired rotational range beforehand.

See also

Image.Matching.PatternMatcher.match

Parameters
Name	Type	Description
locator	HANDLE	The instance to use.
teachImage	CONST_OBJECT Image	The teach image.
teachRegion	CONST_AUTO	A pixel region or closed 2D shape defining which area to consider as containing the object.

Return values
Name	Type	Description
teachPoseTransform	OBJECT Transform	Pose transform of the object model, or nil if unsuccessful.

Sample

teachPose = Image.Matching.PatternMatcher.teach(locator, teachImage, teachRegion)

toString()

Short description

Returns a human readable description of the matcher, including parameters.

Parameters
Name	Type	Description
handle	HANDLE	The matcher instance to use.

Return values
Name	Type	Description
description	STRING	A description of the matcher object, or nil on failure.

Sample

description = Image.Matching.PatternMatcher.toString(handle)

Image.Matching.PatternVerifier

Short description

Verifies a pixel value pattern. Create a new instance using the create function, set parameters using the set functions, teach the correct pattern from a reference image and call verify to find the similarity to the taught pattern. The PatternVerifier can tolerate some errors in the given translation, rotation and scale of the pattern to verify, however for large uncertainties, use a matcher object to find the pattern first. By default all tolerances are set to zero. Results are given as similarity scores as well as an image indicating where the differences are. A refined pose is returned.

Keywords

checking, comparison, pixel, verification, correlation

Overview

create(), generateOverlay(), getModelBoundingBox(), setEdgeSensitivity(), setPositionTolerance(), setRotationTolerance(), setScaleTolerance(), setTimeout(), teach(), toString(), verify()

Functions

create()

Short description

Creates a new pattern verifier for pixel value pattern verification.

Return values
Name	Type	Description
verifier	HANDLE	The new instance.

Sample

verifier = Image.Matching.PatternVerifier.create()

generateOverlay()

Short description

Generates an overlay PixelRegion by thresholding a difference image. The overlay is transformed to match the latest live image and refined pose.

Parameters
Name	Type	Description
verifier	HANDLE	The instance to use.
differenceImage	CONST_OBJECT Image	Difference image to threshold.
threshold	FLOAT	Threshold for difference image, all pixels with values above the threshold will be included in the pixel region.

Return values
Name	Type	Description
overlay	OBJECT Image.PixelRegion	Overlay pixel region, or nil if unsuccessful.

Sample

overlay = Image.Matching.PatternVerifier.generateOverlay(verifier, differenceImage, threshold)

getModelBoundingBox()

Short description

Get a bounding box of the teach object centered on the image world origin. It can be transformed directly by the pose transformations sent to and obtained from verify to visualize the working area of the verifier.

Parameters
Name	Type	Description
verifier	HANDLE	The instance to use.

Return values
Name	Type	Description
modelBox	OBJECT Shape	A rectangle Shape representing the bounding box of the teach region, or nil if unsuccessful.

Sample

modelBox = Image.Matching.PatternVerifier.getModelBoundingBox(verifier)

setEdgeSensitivity()

Short description

Sets the sensitivity to edge pixel intensity values used when verifying. Sharp edges generate large errors for noisy edge positions, setting a low sensitivity (default) reduces errors due to small edge position variations among objects.

Parameters
Name	Type	Description
verifier	HANDLE	The instance to use.
edgeSensitivity	ENUM EdgeSensitivity	Sensitivity to edge pixels (e.g.: HIGH, LOW).

Sample

Image.Matching.PatternVerifier.setEdgeSensitivity(verifier, edgeSensitivity)

setPositionTolerance()

Short description

Sets how much the position of the pattern may deviate from the pose given to the verify function. Narrowing the translational search range speeds up the verification considerably. The range is given as a distance in world units, allowing the pattern to be translated up to plus/minus the distance along both dimensions.

Parameters
Name	Type	Description
verifier	HANDLE	The instance to use.
translation	FLOAT	Allowed distance in world units. The default tolerance is zero.

Sample

Image.Matching.PatternVerifier.setPositionTolerance(verifier, 2.0)

setRotationTolerance()

Short description

Sets how much the rotation of the pattern may deviate from the pose given to the verify function. Narrowing the rotation search range speeds up the verification considerably. The range is given as an angle in radian units. The rotation range interval is plus/minus the specified angle.

Parameters
Name	Type	Description
verifier	HANDLE	The instance to use.
rotationRad	FLOAT	Angle in radian units, the maximum deviation from the given object orientation to search for. The default tolerance is zero.

Sample

Image.Matching.PatternVerifier.setRotationTolerance(verifier, 3.1415/16)

setScaleTolerance()

Short description

Sets how much the scale of the pattern may deviate from the pose given to the verify function. Narrowing the scale search range speeds up the verification considerably. The range is given as the minimum and maximum size of the pattern, relative to the transformation supplied to the verify function. The default is no scale change tolerance, i.e., setScaleTolerance(1.0, 1.0).

Parameters
Name	Type	Description
verifier	HANDLE	The instance to use.
minimumScale	FLOAT	Minimum relative scale to accept, e.g. setting to 0.9 allows pattern sizes down to 90%.
maximumScale	FLOAT	Maximum relative scale to accept, e.g. setting to 1.1 allows pattern sizes up to 110%.

Sample

Image.Matching.PatternVerifier.setScaleTolerance(verifier, 0.9, 1.1)

setTimeout()

Short description

Abort the verify call if the verify time exceeds a user-defined number of seconds. The default value is 5 seconds.

Parameters
Name	Type	Description
verifier	HANDLE	The instance to use.
timeoutSeconds	FLOAT	Time in seconds after which the algorithm should abort.

Sample

Image.Matching.PatternVerifier.setTimeout(verifier, 2.0)

teach()

Short description

Teaches a pattern from an image. The returned pose is usually appended to a Fixture related to the main inspected object.

See also

Image.Matching.PatternVerifier.verify

Parameters
Name	Type	Description
verifier	HANDLE	The instance to use.
teachImage	CONST_OBJECT Image	The teach image.
teachRegion	CONST_OBJECT Image.PixelRegion	A pixel region defining which area to consider as containing the pattern.

Return values
Name	Type	Description
teachPoseTransform	OBJECT Transform	Pose transform of the pattern, or nil if unsuccessful.

Sample

teachPose = Image.Matching.PatternVerifier.teach(verifier, teachImage, teachRegion)

toString()

Short description

Returns a human readable description of the pattern verifier, including parameters.

Parameters
Name	Type	Description
verifier	HANDLE	The instance to use.

Return values
Name	Type	Description
description	STRING	A description of the verifier, or nil on failure.

Sample

description = Image.Matching.PatternVerifier.toString(verifier)

verify()

Short description

Verifies a pattern by comparing to the teach pattern. A teach call must be made first. Some errors in the pose can be tolerated by setting the respective tolerance values.

See also

Image.Matching.PatternVerifier.teach

Parameters
Name	Type	Description
verifier	HANDLE	The instance to use.
liveImage	CONST_OBJECT Image	The live image to verify the pattern in.
pose	CONST_OBJECT Transform	The pose of the pattern to be verified, usually obtained from a Fixture.

Return values
Name	Type	Description
score	FLOAT	A score between 0.0 and 1.0, or nil if unsuccessful. High score means the pattern is similar to the teach pattern.
differenceImage	OBJECT Image	The difference image, indicating where the patterns differ, or nil if unsuccessful. Pixel values close to zero indicate areas where the patterns match. The default image contains the absolute pixel value differences between the live image and the transformed teach pattern. The difference image is sampled in an object-centered coordinate system with the origin in the center of the image, and cropped to the bounding box of the teach pattern. Any indications in the difference image should be transformed using the refinedPose to obtain the corresponding position in the live image.
refinedPose	OBJECT Transform	The refined pose of the pattern, or nil if unsuccessful. If all tolerances are set to zero, this will be equal to the given pose.

Sample

score, differenceImage, refinedPose = Image.Matching.PatternVerifier.verify(verifier, liveImage, pose)

Image.Matching.PointMatcher

Short description

Finds an object in an image based on feature points. Salient points are found on the reference object and similar points are searched for in the live images. Teach the object from a reference image and call match to find the location of the same object in a live image. The strength of the PointMatcher relative the EdgeMatcher is for objects whose appearance can be described in terms of textured pattern rather than clear edges or contours. The PointMatcher can also easily find large scale or perspective changes which the EdgeMatcher cannot. The outputs from the PointMatcher are a so-called pose transform and a match score. The pose transform is a Transform object which transforms the model points extracted in the teach step to the matched location in the live image. The PointMatcher is often used together with the Fixture object that facilitates local coordinate transforms based on the pose transform. The match score is a number between 0.0 and 1.0 indicating the fraction of model points that have a match in the input image. The most important parameters for the PointMatcher are the following: - Pose type: This parameter tells the PointMatcher which type of appearance change to look for in the match process, e.g., does the object of interest change size relative to the teach object, does the camera position change leading to a perspective change of the imaged object, etc.? Restrict the pose type as much as possible for a more robust matching. By default, the pose type is restricted and must explicitly be set to allow more general pose transforms. See the documentation of the setPoseType-function for more information. - Pose variability: If the object of interest is imaged from very different angles or distances, leading to large perspective or scale changes, set the pose variability to HIGH for more robustness. Otherwise, set the pose variability to LOW for a higher matching speed. Use the setPoseVariability-function to set the pose variability. - Point count: The target number of salient points to extract. Fewer points will make the matching faster, but with too few points the matching will fail. Use setPointCount() to reduce the number of points. - Downsample factor: Tells the PointMatcher to work on a downsampled version of the input image. This can increase speed and in some cases even robustness if the original image is of high-resolution. Setting the downsample factor too high reduces the robustness though as the feature points in the ensuing low resolution image are not distinct enough. - Rotation range: The rotation range narrows the expected rotations relative to the teach pose. This parameter does not affect matching speed but increases robustness as false matches can be rejected. Set this range as narrow as possible but still wide enough to let valid matches through. - Scale range: The scale range narrows the expected scale change to the teach pose. This parameter does not affect matching speed but increases robustness as false matches can be rejected. Set this range as narrow as possible but still wide enough to let valid matches through. Restrictions: - Only uint8 images are accepted. - The PointMatcher can currently only find 1 object instance per image. Image world coordinate system handling: The image (x,y)-pixelsize and origin are considered, all calculations are made in the image world coordinate system. The output pose transforms are also expressed in the image world coordinate system. Missing data handling: The PointMatcher does not accept missing data images, remove missing data first before usage.

Keywords

descriptor, feature point, interest point, keypoint, landmark, matching, object, perspective, locator

Overview

create(), getDetectedPoints(), getModelPoints(), getTeachPose(), match(), setDownsampleFactor(), setIterations(), setOutlierMargin(), setPointCount(), setPoseType(), setPoseVariability(), setRotationRange(), setScaleRange(), setTimeout(), teach(), toString()

Functions

create()

Short description

Creates a new point matcher for 2D object localization.

Return values
Name	Type	Description
locator	HANDLE	The new instance.

Sample

locator = Image.Matching.PointMatcher.create()

getDetectedPoints()

Short description

Fetches two lists with salient points that were detected in the live image during the last match call. Points are returned in world coordinates and are intended to be plotted directly on the live image for graphical feedback. The first list contains all detected points while the second list only contains those points that were matched and found to be geometrically consistent with the corresponding model point under the found pose transformation.

Parameters
Name	Type	Description
locator	HANDLE	The instance to use.

Return values
Name	Type	Description
detectedPointsWorld	OBJECT Point	Detected salient points during the last call to match, may be empty.
matchedPointsWorld	OBJECT Point	Matched points in the last live image, in world coordinates. The matched points are a subset of the detected salient points.

Sample

detectedPointsWorld, matchedPointsWorld = Image.Matching.PointMatcher.getDetectedPoints(locator)

getModelPoints()

Short description

Gets the list of salient points detected during the last teach call as a vector of 2D Points. The points are returned in internal model coordinates and must be transformed using a pose transform to overlay them onto the teach or live image. A maximum number of points to return may be specified. The default is to return all points. This function is intended for graphical feedback. Note: to control the number of points detected in the image and used when matching, use the setPointCount function.

Parameters
Name	Type	Description
locator	HANDLE	The instance to use.
maxCount	INT	Optional parameter to specify the maximum number of points to return. Default is to return all points. Note that one can obtain fewer points than the value specified here.

Return values
Name	Type	Description
points	OBJECT Point	Salient model points in internal model coordinates, may be empty.

Sample

points = Image.Matching.PointMatcher.getModelPoints(locator, maxCount)

getTeachPose()

Short description

Returns the teach pose that was created and returned by the last teach call. If the last teach was unsuccessful, nil is returned.

Parameters
Name	Type	Description
matcher	HANDLE	The instance to use

Return values
Name	Type	Description
teachPose	OBJECT Transform	Pose transform transforming the object model to its position in the teach image, or nil if unsuccessful.

Sample

teachPose = Image.Matching.PointMatcher.getTeachPose(matcher)

match()

Short description

Finds objects in an image by matching with the teach model. A teach call must be made first. The output is a vector of pose transforms with one or zero entries, or nil. An empty vector indicates that no object was found while nil indicates that the matcher encountered an error. The transform describes how the object model is transformed to matched positions in the live image. The optional search region indicates where salient points will be extracted and should include the entire area where the object may appear. By default, the entire image is used. Use getDetectedPoints after match to visualize detected salient points in the live image and salient points matched to the model.

See also

Image.Matching.PointMatcher.teach

Parameters
Name	Type	Description
locator	HANDLE	The matcher instance to use.
liveImage	CONST_OBJECT Image	The live image to find the object in.
searchRegion	CONST_OBJECT Shape	Optional search region in the live image, must be a rectangle.

Return values
Name	Type	Description
poseTransforms	OBJECT Transform	Pose transform defining the location of any detected object. Note that this is a vector with at most one element/transform for future compatibility when adding multiple matches.
matchScores	FLOAT	A score between 0.0 and 1.0 for any detected object (high score means good match). Note that this is a vector with at most one element/score for future compatibility when adding multiple matches.
inlierRMS	FLOAT	The root mean squared error among inlier points in world coordinates (lower is better). Note that this is a vector with at most one element/value for future compatibility when adding multiple matches.

Sample

poseTransforms, matchScores, inlierRMS = Image.Matching.PointMatcher.match(locator, liveImage)

setDownsampleFactor()

Short description

Sets the factor in the x- and y-dimensions for the internal downsampling of the image. Increasing this value will reduce the time required for detecting salient points. A larger downsampling factor may improve results in cases where the image structure is smooth or slightly out of focus. A higher downsampling factor reduces the accuracy of the estimated pose.

Parameters
Name	Type	Description
matcher	HANDLE	The instance to use. Default is 2.0.
downsampleFactor	FLOAT	A factor larger than or equal to 1.0.

Sample

Image.Matching.PointMatcher.setDownsampleFactor(matcher, downsampleFactor)

setIterations()

Short description

Sets the maximum number of iterations in the geometrical robust fitting step. Decreasing this parameter makes the geometrical matching faster, however using too small values, good matches may be missed. When a match with high probability of being the correct one is found, fewer iterations may be used. The number of iterations set here is also used to control the probability threshold, where a higher number of iterations corresponds to requiring a higher probability of a correct match before stopping the iteration in advance.

Parameters
Name	Type	Description
locator	HANDLE	The instance to use.
iterations	INT	Number of iterations, must be larger than one, the default is 5000.

Sample

Image.Matching.PointMatcher.setIterations(locator, iterations)

setOutlierMargin()

Short description

Set the outlier margin in world units, must be greater than zero. The point matcher searches for the transform that is supported by the highest number of salient points. This setting determines how far a transformed model point can be from the corresponding live image point before it is considered an outlier and not supporting the current transform hypothesis. Decreasing this parameter will require the salient points of the template and live images to be geometrically more coherent. A too small value will remove almost all point match candidates, which will reduce object match accuracy significantly.

Parameters
Name	Type	Description
locator	HANDLE	The instance to use.
margin	FLOAT	Outlier margin in world units, the default is 5.0.

Sample

Image.Matching.PointMatcher.setOutlierMargin(locator, margin)

setPointCount()

Short description

Sets the desired number of salient points to detect in an image. The final number of points may be larger or smaller. The desired number of points is related to the full image. For a part of an image, the number of found points is lower in general.

Parameters
Name	Type	Description
locator	HANDLE	The instance to use.
desiredPointCount	INT	A larger number generates more keypoints, default 1000.

Sample

Image.Matching.PointMatcher.setPointCount(locator, desiredPointCount)

setPoseType()

Short description

The pose type puts a limit on the generality of pose transforms returned by the match function. In the following list, the first option is the most restrictive and every new type contains all previously listed types as special cases. "RIGID" - Searches for objects whose image appears translated and rotated. The scale range is ignored in this mode. Set rotation range to zero for pure translations. "SIMILARITY" - Searches for objects whose image appears translated, rotated and uniformly scaled. This is the default option. Set rotation range to zero for translation and scaling only. "AFFINE" - Searches for objects whose image appears translated, rotated, non-uniformly scaled and skewed. "HOMOGRAPHY" - This is the most general transform, it allows e.g. out-of-plane rotation for flat objects.

Parameters
Name	Type	Description
locator	HANDLE	The instance to use.
poseTransformType	ENUM Image.Matching.PointMatcher.PoseType	The type of pose transformation to allow when searching for matching objects.

Sample

Image.Matching.PointMatcher.setPoseType(locator, poseTransformType)

setPoseVariability()

Short description

Set to the expected variability in pose of the objects in the live image. Setting a higher variability will use more robust salient point detectors and descriptors but those will be slower in most cases. In general, try the lowest setting first and change to higher settings if required. "HIGH" - The default value, more robust but also slower in general. "LOW" - Faster in general and should be fine for any rotation, scale changes up to at least 30% and small perspective effects. When using this mode, the image size in pixels must be the same for all images.

Parameters
Name	Type	Description
locator	HANDLE	The instance to use.
variability	ENUM PoseVariability	The expected pose variability of objects in the live image.

Sample

Image.Matching.PointMatcher.setPoseVariability(locator, variability)

setRotationRange()

Short description

Sets rotation interval to search within, in relation to the teach orientation. The search range is given as a positive angle in radians. The rotation range interval is plus/minus the specified angle. The default value is PI radians, i.e., equal to a full rotation of plus/minus 180 degrees. For the point matcher, the search time is not affected by the rotation range. A too narrow range will remove all tentative matches. If prior orientation information is known, the prior rotation can be set to allow a more narrow search range. The final search range is then up to plus/minus the search range parameter starting from the prior rotation. These parameters can be updated in a teached matcher without re-teaching. When pose type is set to RIGID or SIMILARITY, setting the rotation range to zero will force the matcher to look for pure translations, or translation and scaling only.

Parameters
Name	Type	Description
matcher	HANDLE	The instance to use.
rotationRad	FLOAT	Angle in radians, the maximum deviation from the original object orientation to search for. The default value is PI. Input is silently clamped to the range from 0 to PI.
priorRotationRad	FLOAT	Optional prior orientation in radians. If specified, the orientation search range is centered around this orientation. Default is zero (i.e. same orientation as teach object).

Sample

Image.Matching.PointMatcher.setRotationRange(matcher, rotationRad)

setScaleRange()

Short description

Sets scale interval where objects are expected to appear. Tentative objects with a scale outside the scale range are discarded. Default range is from 0.5 to 2.0, searching for object from half to twice the size of the teach object. For transform types without a specific scale (affine and homogeneous), an approximate apparent scale is used. The scale range is ignored when the matcher is in rigid mode. For the point matcher, the search time is not affected by the scale range. A too narrow range will remove all tentative matches. An optional prior scale can be set, this affects both the minimum and maximum scale (both limits are multiplied with the prior scale). The prior scale accepts a larger range of values than the min and max scale parameters. If the object to find has a fixed non-unit scale relative to the teach object, or if prior information on the scale of the object is available, use the prior scale. The default value is 1.0. By setting both minScale and maxScale to 1.0, scale search is disabled but the prior scale parameter still has effect. These parameters can be updated in a teached matcher without re-teaching.

Parameters
Name	Type	Description
matcher	HANDLE	The instance to use.
minScale	FLOAT	The smallest scale factor to allowed.
maxScale	FLOAT	The largest scale factor to allowed.
priorScale	FLOAT	Optional prior scale factor. Set to the expected scale of the object to find, relative to the size of the teach object. E.g. 1.25 if the object to find is 25% larger than the teach object.

Sample

Image.Matching.PointMatcher.setScaleRange(matcher, minScale, maxScale)

setTimeout()

Short description

Abort the match call if the match time exceeds a user-defined number of seconds. The default value is 5 seconds.

Parameters
Name	Type	Description
locator	HANDLE	The instance to use.
timeoutSeconds	FLOAT	Time in seconds after which the algorithm should abort.

Sample

Image.Matching.PointMatcher.setTimeout(locator, timeoutSeconds)

teach()

Short description

Teaches an object model from an image. Use getModelPoints after teach to visualize the detected salient points on the teach object.

See also

Image.Matching.PointMatcher.match

Parameters
Name	Type	Description
locator	HANDLE	The instance to use.
teachImage	CONST_OBJECT Image	The teach image.
teachRegion	CONST_AUTO	A pixel region or closed 2D shape defining which area to consider as containing the object.

Return values
Name	Type	Description
teachPoseTransform	OBJECT Transform	Pose transform of the object model, or nil if unsuccessful.

Sample

teachPose = Image.Matching.PointMatcher.teach(locator, teachImage, teachRegion)

toString()

Short description

Get a user-friendly string description of the matcher. The parameters are the internal parameters of the matcher, call teach for parameter changes to take effect and appear in the description string.

Parameters
Name	Type	Description
locator	HANDLE	The instance to use.

Return values
Name	Type	Description
description	STRING	User-friendly description of the matcher.

Sample

description = Image.Matching.PointMatcher.toString(locator)

Image.OCR

Image.OCR.Halcon

Overview

findTextLineOrientation(), rotateImage()

Functions

findTextLineOrientation()

Short description

Finds the orientation of a text line in an image. The text line is assumed to be darker than the background

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	Input region where the text line is located
image	CONST_OBJECT Image	Input sample
charHeightPix	INT	Character height
orientationFromRad	FLOAT	Start of search interval
orientationToRad	FLOAT	End of search interval

Return values
Name	Type	Description
orientationAngleRad	FLOAT	Orientation of text line in radians

Sample

local orientationAngleRad = Image.OCR.Halcon.findTextLineOrientation(region, image, charHeightPix, orientationFromRad, orientationToRad)

rotateImage()

Short description

Rotates an image.

Parameters
Name	Type	Description
image	CONST_OBJECT Image	Input image
orientationAngleRad	FLOAT	Orientation of text line in radians

Return values
Name	Type	Description
rotatedImage	OBJECT Image	The rotated image

Sample

local rotatedImage = Image.OCR.Halcon.rotateImage(image, phi)

Image.OCR.Halcon.AutoSegmenter

Short description

Automatically segments text in an image.

Overview

create(), findText(), setParameter()

Functions

create()

Short description

Creates an instance of a OCR.Halcon.AutoSegmenter.

Return values
Name	Type	Description
handle	HANDLE	Instance handle of the AutoSegmenter.

Sample

handle = Image.OCR.Halcon.AutoSegmenter.create()

findText()

Short description

Segments an image into text lines and characters.

Parameters
Name	Type	Description
handle	HANDLE	Instance handle of the configuration.
image	CONST_OBJECT Image	Input sample
region	CONST_OBJECT Image.PixelRegion	Optional region of interest. If supplied, the find text operation is only performed within the bounding box of is region. This can save a lot of computation time if the region is small.

Return values
Name	Type	Description
textLines	OBJECT Image.OCR.Halcon.SegmenterResult	Result with found text lines.

Sample

local textLines = Image.OCR.Halcon.AutoSegmenter.findText(handle, image)

setParameter()

Short description

Sets a parameter used to help/guide the automatic segmentation of the image into text lines.

Parameters
Name	Type	Description
handle	HANDLE	Instance handle of the configuration.
paramName	ENUM AutoSegmentationParameters	Name of parameter.
paramValue	AUTO	Flexible parameter to set a segmentation parameter. Could be a string, an integer value or a float value.

Sample

Image.OCR.Halcon.AutoSegmenter.setParameter(handle, paramName, paramValue)

Image.OCR.Halcon.FontClassifier

Short description

Classifies text in an image using a pre-trained font classifier.

Overview

classifyCharacters(), create(), setFont()

Functions

classifyCharacters()

Short description

Finds characters in one text line. The text line must first be segmented into individual characters and supplied as a vector of pixelregions.

Parameters
Name	Type	Description
handle	HANDLE	Instance handle of the configuration.
textline	CONST_OBJECT Image.PixelRegion	Array of pixel regions each containing a text character
image	CONST_OBJECT Image	Image with text
expression	STRING	Regular expression (Perl Compatible Regular Expressions) defining the allowed set of characters

Return values
Name	Type	Description
characters	STRING	Classified characters. If the used fonts has a rejection class (name ends with _REJ) the ASCII code \x1A is returned whenever a character can not be classified
confidence	FLOAT	The confidence for each found character
regExpScore	FLOAT	The score for how well the found characters match the regular expression. Set to 1.0 if no expression is used.

Sample

local characters, confidence, regExpScore = Image.OCR.Halcon.FontClassifier.classifyCharacters(handle, textline, image, expression)

create()

Short description

Creates an instance of a OCR.Halcon.FontClassifier

Return values
Name	Type	Description
handle	HANDLE	Instance handle of the FontClassifier.

Sample

handle = Image.OCR.Halcon.FontClassifier.create()

setFont()

Short description

Set which pre-trained font classifier to used. Font names ending with _Rej have a rejection class. With fonts that provide a rejection class, it is possible to distinguish characters from background clutter. Fonts with a rejection class return the ASCII Code 26, which is SUB (substitute) if no letter was found.

Parameters
Name	Type	Description
handle	HANDLE	Instance handle of the configuration.
fontName	ENUM PreTrainedFonts	Name of pre-trained font. Default value: 'INDUSTRIAL_REJ'

Sample

Image.OCR.Halcon.FontClassifier.setFont(handle, mode, fontName)

Image.OCR.Halcon.ManualSegmenter

Short description

Segments text in an image based on user input.

Overview

create(), findText(), setParameter()

Functions

create()

Short description

Creates an instance of a OCR.Halcon.ManualSegmenter.

Return values
Name	Type	Description
handle	HANDLE	Instance handle of the ManualSegmenter.

Sample

handle = Image.OCR.Halcon.ManualSegmenter.create()

findText()

Short description

Segments an image into text lines and characters.

Parameters
Name	Type	Description
handle	HANDLE	Instance handle of the configuration.
image	CONST_OBJECT Image	Input sample
region	CONST_OBJECT Image.PixelRegion	Optional region of interest. If supplied, the filter operation is only performed within the bounding box of is region. This can save a lot of computation time if the region is small.

Return values
Name	Type	Description
textLines	OBJECT Image.OCR.Halcon.SegmenterResult	Result with found text lines.

Sample

local textLines = Image.OCR.Halcon.ManualSegmenter.findText(handle, image)

setParameter()

Short description

Sets a parameter used when segmenting the image for text lines.

Parameters
Name	Type	Description
handle	HANDLE	Instance handle of the configuration.
paramName	ENUM ManualSegmentationParameters	Name of parameter.
paramValue	AUTO	Flexible parameter to set a segmentation parameter. Could be a string, an integer value or a float value.

Sample

Image.OCR.Halcon.ManualSegmenter.setParameter(handle, paramName, paramValue)

Image.OCR.Halcon.SegmenterResult

Short description

Segmentation result from either the ManualSegmenter or the AutoSegmenter. Contains all found text lines. Each text line is stored as a vector of PixelRegions.

Overview

getNumberOfTextLines(), getTextLine()

Functions

getNumberOfTextLines()

Short description

Returns the number of found text lines.

Parameters
Name	Type	Description
result	CONST_OBJECT Image.OCR.Halcon.SegmenterResult	The segmentation result to use.

Return values
Name	Type	Description
numTextLines	INT	The number of text lines.

Sample

numTextLines = Image.OCR.Halcon.SegmenterResult.getNumberOfTextLines(result)

getTextLine()

Short description

Returns the text line with the given index.

Parameters
Name	Type	Description
result	CONST_OBJECT Image.OCR.Halcon.SegmenterResult	The segmentation result to use.
index	INT	Index of the text line.

Return values
Name	Type	Description
textLine	OBJECT Image.PixelRegion	The text line as a vector of PixelRegions.

Sample

textLine = Image.OCR.Halcon.SegmenterResult.getTextLine(result, index)

Image.PixelRegion

Short description

A PixelRegion represents a collection of pixels in an image. A common use-case is to represent regions or masks in an image and the underlying representation is therefore run-length coded in form of a list of connected row-segments. This makes the representation computationally efficient to work with. The pixels in a PixelRegion need not be connected though, but can consist of isolated pixels or a set of connected regions. It is assumed that a PixelRegion is used together with an Image object in which it defines the collection of pixels. The PixelRegion therefore knows only about pixel coordinates and is not aware of the Image object’s world coordinate system. For measurements inside the given PixelRegion or for transformations of the PixelRegion requiring the Image world coordinate system, the reference Image object must also be supplied as parameter to the corresponding functions. The PixelRegion can be obtained as a rasterized Shape object, but there is currently no function for converting a PixelRegion to a Shape object. A PixelRegion can be generated from an Image object, for example through a threshold operation, and it is possible to render a PixelRegion back into an Image object.

Functions

contains()

Short description

Return true if the region(s) contains the given point. If more than one region is provided true is returned if the point is inside any of the regions. If more than one point is provided an array is returned with one value for each input point.

Keywords

included, inside

See also

Shape.contains

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	Input region(s)
point	CONST_OBJECT Point	Input point(s)

Return values
Name	Type	Description
result	BOOL	True if the point is within the region(s), otherwise false

Sample

result = Image.PixelRegion.contains(region, point)

countBorderPixels()

Short description

Return the number of border pixels of the region. A border pixel is located within the region and with neighboring pixels outside the region. 4-connectivity is used for the neighbor relation.

See also

Image.PixelRegion.getBorderRegion

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	Input region or region list

Return values
Name	Type	Description
pixelCount	INT	Computed number of border pixels (single value or list)

Sample

pixelCount = Image.PixelRegion.countBorderPixels(region)

countHoles()

Short description

Return the number of holes in the region. To avoid including very small holes that only represent image noise, consider performing a dilate operation before calling countHoles.

See also

Image.PixelRegion.fillHoles

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	Input region or region list

Return values
Name	Type	Description
holeCount	INT	Computed number of holes (single value or list)

Sample

holeCount = Image.PixelRegion.countHoles(region)

countPixels()

Short description

Return the number of pixels within the region.

Keywords

area

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	Input region or region list

Return values
Name	Type	Description
pixelCount	INT	Computed number of pixels (single value or list)

Sample

pixelCount = Image.PixelRegion.countPixels(region)

createCircle()

Short description

Create a pixel region containing all pixels within the given circle. By providing vectors of centers and radii several pixel regions can be created. All vectors must be of equal length.

Parameters
Name	Type	Description
center	CONST_OBJECT Point	Circle center. Can also be a vector to create several regions.
radius	FLOAT	Circle radius. Can also be a vector to create several regions.

Return values
Name	Type	Description
region	OBJECT Image.PixelRegion	The created pixel region, or vector of pixel regions for vector input.

Sample

region = Image.PixelRegion.createCircle(Point.create(100,100), 20)

createEmpty()

Short description

Create an empty region.

Return values
Name	Type	Description
region	OBJECT Image.PixelRegion	The created empty pixel region.

Sample

region = Image.PixelRegion.createEmpty()

createFromPoints()

Short description

Create a PixelRegion from a set of 2D points defined in image world coordinates. Any points outside the reference image bounds are ignored. By default, each point sets one pixel in the output region. The region point size can be adjusted by the pointDiameter parameter.

Keywords

toPixelRegion

Parameters
Name	Type	Description
points	CONST_OBJECT Point	List of world coordinates, represented as 2D Point objects, for each pixel in the region.
referenceImage	CONST_OBJECT Image	Reference image, defines the image world coordinate system.
pointDiameter	INT	Diameter of the points to create, in pixels. Point diameter must be odd and positive. Optional, default is one.

Return values
Name	Type	Description
region	OBJECT Image.PixelRegion	The generated pixel region

Sample

region = Image.PixelRegion.createFromPoints(points, referenceImage, pointDiameter)

createRectangle()

Short description

Create a pixel region containing all pixels within a rectangle with upper-left corner (x0,y0) and lower-right corner (x1,y1). By providing vectors of corners several pixel regions can be created. All vectors must be of equal length.

Parameters
Name	Type	Description
x0	INT	x0 (upper-left). Can also be a vector to create several regions.
y0	INT	y0 (upper-left). Can also be a vector to create several regions.
x1	INT	x1 (lower-right). Can also be a vector to create several regions.
y1	INT	y1 (lower-right). Can also be a vector to create several regions.

Return values
Name	Type	Description
region	OBJECT Image.PixelRegion	The created pixel region, or vector of pixel regions for for vector input.

Sample

region3 = Image.PixelRegion.createRectangle(x0, y0, x1, y1)

dilate()

Short description

Dilate the input region with a disc of the given pixel diameter.

Keywords

morphology, expand

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	Input region or list of regions.
diameter	INT	Disc diameter in pixels (must be odd).

Return values
Name	Type	Description
outputRegion	OBJECT Image.PixelRegion	Dilated region or list of regions, or nil on error.

Sample

outputRegion = Image.PixelRegion.dilate(region, diameter)

downsample()

Short description

Downsample the pixel region(s) by an integer factor, keeping only rows and columns with coordinates equal to n*factor, where n = 0,1,2,…

Parameters
Name	Type	Description
inputRegion	CONST_OBJECT Image.PixelRegion	Input region(s).
factor	INT	Downsample factor. Must be larger than zero.

Return values
Name	Type	Description
outputRegion	OBJECT Image.PixelRegion	Input region(s) downsampled by the provided factor.

Sample

outputRegion = Image.PixelRegion.downsample(inputRegion, 2)

erode()

Short description

Erode the input region with a disc of the given pixel diameter.

Keywords

morphology, shrink

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	Input region or list of regions.
diameter	INT	Disc diameter in pixels (must be odd).

Return values
Name	Type	Description
outputRegion	OBJECT Image.PixelRegion	Eroded region or list of regions, or nil on error.

Sample

outputRegion = Image.PixelRegion.erode(region, diameter)

fillHoles()

Short description

Fill any holes in a region.

See also

Image.PixelRegion.fillRegion

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	Input region.

Return values
Name	Type	Description
outputRegion	OBJECT Image.PixelRegion	Output region, where any holes in the input region has been filled.

Sample

outputRegion = Image.PixelRegion.fillHoles(region)

fillRegion()

Short description

Keywords

inpaint, flood

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	The region(s) to fill.
value	FLOAT	World coordinate value to set for pixels within the region. A vector with three values must be given if the input image is an RGB image.
inputImage	CONST_OBJECT Image	Input image.

Return values
Name	Type	Description
outputImage	OBJECT Image	Result image or nil if operation failed.

Sample

outputImage = Image.PixelRegion.fillRegion(region, value, inputImage)

fillRegionInplace()

Short description

Inplace version of the Image.PixelRegion.fillRegion function that modifies the input image. See base function for full documentation.

Keywords

inpaint, flood

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	The region(s) to fill.
value	FLOAT	World coordinate value to set for pixels within the region. A vector with three values must be given if the input image is an RGB image.
image	OBJECT Image	The image. This image is overwritten with the result image.

Return values
Name	Type	Description
result	OBJECT Image	Reference to the result image.

Sample

result = Image.PixelRegion.fillRegionInplace(region, value, image)

findConnected()

Short description

Find the connected components of an input pixel region, i.e., splits a PixelRegion object into a list of separated regions. Only keeps regions with a size (counted in number of pixels) within the range [minSize, maxSize].

Keywords

blob extraction, labeling, connected components

Parameters
Name	Type	Description
inputRegions	CONST_OBJECT Image.PixelRegion	Input region(s)
minSize	INT	Minimum output region size
maxSize	INT	Maximum output region size
maxRegionCount	INT	Maximum number of output regions to return (default is 1000). Used to limit the memory requirements of the algorithm.

Return values
Name	Type	Description
result	OBJECT Image.PixelRegion	List of connected components represented as pixel regions, sorted by decreasing size

Sample

regions = Image.PixelRegion.findConnected(inputRegion, 10)

getArea()

Short description

Return the area of the specified region. This is equal to the number of pixels in the region times the area of each pixel as specified by the pixel sizes in the x,y-dimensions. Missing data handling: Any missing data information of the referenceImage is ignored. The area is calculated purely on the pixelRegion and scaled using the pixel scale of the image world coordinate system.

See also

Image.PixelRegion.getVolume

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	Input region or region list
referenceImage	CONST_OBJECT Image	Reference image, defining the image world coordinate system.

Return values
Name	Type	Description
area	FLOAT	Region area or areas in world units

Sample

area = Image.PixelRegion.getArea(region, referenceImage)

getBorderRegion()

Short description

Get the border pixels of the input region as a new pixel region. Border pixels are pixels within the input region bordering to pixels outside the region.

Keywords

edge, perimeter

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	Input region or list of regions

Return values
Name	Type	Description
borderRegion	OBJECT Image.PixelRegion	Output border region or list of regions

Sample

outputRegion = Image.PixelRegion.getBorderRegion(region)

getBoundingBox()

Short description

Return an axis-aligned box of the region as a rectangle Shape in image world coordinates. To get the bounding box in pixel coordinates instead, just omit the optional referenceImage parameter.

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	Input region or region list.
referenceImage	CONST_OBJECT Image	Reference image, defining the image world coordinate system.

Return values
Name	Type	Description
box	OBJECT Shape	Bounding box, represented as a rectangle Shape object, always with zero rotation (single box or list).

Sample

box = Image.PixelRegion.getBoundingBox(region)

getBoundingBoxOriented()

Short description

Returns the rectangle (not necessarily axis-aligned) of minimum area containing the object. The area is computed in world coordinates. The rectangle is oriented such that the width is larger or equal to the height and with the orientation angle in the range (0..PI).

See also

Image.PixelRegion.getBoundingBox

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	Input region or region list
referenceImage	CONST_OBJECT Image	Reference image, used to define the image world coordinate system
accuracyRad	FLOAT	Required accuracy of the rotation (maximal error of the reported rotation, in radians). Affects both accuracy and speed.

Return values
Name	Type	Description
rectangle	OBJECT Shape	The computed oriented bounding box, represented as a rectangle Shape object (single object or list)

Sample

rectangle = Image.PixelRegion.getBoundingBoxOriented(region, referenceImage)

getCenterOfGravity()

Short description

Return the center of gravity of the region in image world coordinates. Missing data handling: Any missing data information of the referenceImage is ignored. The center of gravity is calculated purely on the pixelRegion compensated for image scale and origin.

Keywords

cog

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	Input region or region list
referenceImage	CONST_OBJECT Image	Reference image, defining the image world coordinate system

Return values
Name	Type	Description
point	OBJECT Point	Center of gravity represented as a 2D Point object (single point or list of points)

Sample

point = Image.PixelRegion.getCenterOfGravity(region, referenceImage)

getCircularity()

Short description

Returns a circularity measure that is 1.0 for ideal circles and smaller for other shapes. The measure is robust to high-frequency noise like jagged edges along the circle perimeter, so even noisy circles get a measure close to 1.0. The measure is significantly lower if the overall appearance is rather an ellipse, square or other non-circular shape.

Keywords

roundness

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	Input region or region list

Return values
Name	Type	Description
circularity	FLOAT	The computed circularity measure (single value or list)

Sample

circularity = Image.PixelRegion.getCircularity(region)

getCompactness()

Short description

Returns the compactness measure of the region (4 * PI * Area / Perimeter^2). This is close to 1.0 for circles and smaller for less compact regions.

Keywords

roundness

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	Input region or region list
referenceImage	CONST_OBJECT Image	Reference image, used to define the image world coordinate system

Return values
Name	Type	Description
compactness	FLOAT	The computed compactness measure (single value or list)

Sample

compactness = Image.PixelRegion.getCompactness(region, referenceImage)

getConvexHull()

Short description

Get the convex hull of the input pixel region.

Parameters
Name	Type	Description
sourceRegion	CONST_OBJECT Image.PixelRegion	Input region or list of regions

Return values
Name	Type	Description
outputRegion	OBJECT Image.PixelRegion	Target region or list of regions, convex hull of the input

Sample

outputRegion = Image.PixelRegion.getConvexHull(sourceRegion)

getConvexity()

Short description

Returns the convexity measure of the region (region area divided by area of convex hull). This is 1.0 for convex regions and smaller the more non-convex the region is

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	Input region or region list

Return values
Name	Type	Description
convexity	FLOAT	The computed convexity measure (single value or list)

Sample

convexity = Image.PixelRegion.getConvexity(region)

getDifference()

Short description

Get the set difference of the input regions. Returns a new region containing all pixels present in the first region but not in the second. If two regions are give, the function returns the difference of the two regions. If one list and one region is given, the function returns a list of regions containing the differences of each region in the list and the single region. If two lists are given, the function returns a list of regions containing the pair-wise difference of the regions in the lists. The lists must be the same length.

Parameters
Name	Type	Description
region1	CONST_OBJECT Image.PixelRegion	First input region, or list of regions
region2	CONST_OBJECT Image.PixelRegion	Second input region, or list of regions

Return values
Name	Type	Description
outputRegion	OBJECT Image.PixelRegion	Resulting region or list of regions

Sample

outputRegion = Image.PixelRegion.getDifference(region1, region2)

getElongation()

Short description

Get the elongation of the region, defined as the ratio between the principal axes lengths. This measure is also often called eccentricity. The value is 1.0 for circles larger than 1.0 for regions that are elongated in one direction.

Keywords

eccentricity

See also

Image.PixelRegion.getPrincipalAxes

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	Input region or region list
referenceImage	CONST_OBJECT Image	Reference image, used to define the image world coordinate system

Return values
Name	Type	Description
elongation	FLOAT	Computed elongation measure (single value or list)

Sample

elongation = Image.PixelRegion.getElongation(region, referenceImage)

getHistogram()

Short description

Get a histogram of the image values within the specified region. If the image supports missing data, pixels marked as missing are not included in the histogram. If a pixel-world mapping is specified, the histogram is computed using world coordinates. If the bounds are skipped, the entire image value range is used for 8-channel images, and the range between the current minimum and maximum value is used for other image types. Optionally, a reference surface in world coordinates may be provided, in which case the histogram is based on deviations from the reference surface. The default surface is the plane z=0. See also Image.getHistogram.

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	Region specifying which parts of the image to include in the histogram
image	CONST_OBJECT Image	Input image, specifying values to use in the histogram
binCount	INT	Number of bins. Uses 32 bins as default.
minValue	FLOAT	Minimum of the value range to cover. Uses an automatic range if omitted.
maxValue	FLOAT	Maximum of the value range to cover. Uses an automatic range if omitted.
referenceSurface	CONST_OBJECT Shape3D	Zero-reference surface for the histogram. Optional, default is the plane z=0.

Return values
Name	Type	Description
histogram	FLOAT	Histogram, represented as a vector of floats
binCenters	FLOAT	The center of each histogram bin in the input value range

Sample

histogram, centers = Image.PixelRegion.getHistogram(region, image, 64)

getIntersection()

Short description

Get the set intersection of two regions. If two regions are give, the function returns the set intersection of the two regions. If one list and one region is given, the function returns a list of regions containing the intersections of each region in the list and the single region. If two lists are given, the function returns a list of regions containing the pair-wise intersection of the regions in the lists. The lists must be the same length.

Parameters
Name	Type	Description
region1	CONST_OBJECT Image.PixelRegion	First input region, or list of regions
region2	CONST_OBJECT Image.PixelRegion	Second input region, or list of regions, subtracted from region1

Return values
Name	Type	Description
outputRegion	OBJECT Image.PixelRegion	Resulting region or list of regions

Sample

outputRegion = Image.PixelRegion.getIntersection(region1, region2)

getMedian()

Short description

Get the median value of the pixels within the region, a special case of Image.PixelRegion.getPercentiles. The median is derived from a histogram and it is approximate. Optionally, a reference surface in world coordinates may be provided, in which case the deviations from the reference surface are considered. The default surface is the plane z=0.

Keywords

percentile, statistics

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	Input region or region list
image	CONST_OBJECT Image	Input image, defines the image from which to get pixel value input.
referenceSurface	CONST_OBJECT Shape3D	Zero-reference 3D surface plane for pixel world coordinate values. Optional, default is the plane z=0.

Return values
Name	Type	Description
median	FLOAT	The approximate median.

Sample

median = Image.PixelRegion.getMedian(region, image, referenceSurface)

getPercentiles()

Short description

Get a set of rank measurement according to the specified percentile levels. Level 0.5 gives the median, level 0.9 give a value larger than 90% of all image pixels, etc. All values are derived from a histogram and are approximate. Optionally, a reference surface in world coordinates may be provided, in which case the deviations from the reference surface are considered. The default surface is the plane z=0.

Keywords

statistics

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	Input region
image	CONST_OBJECT Image	Input image, defines the image from which to get pixel value input.
percentileLevels	FLOAT	Percentile levels in the range (0..1)
referenceSurface	CONST_OBJECT Shape3D	Zero-reference 3D surface plane for pixel world coordinate values. Optional, default is the plane z=0.

Return values
Name	Type	Description
values	FLOAT	Output values

Sample

values = Image.PixelRegion.getPercentiles(region, image, percentileLevels, referenceSurface)

getPerimeterLength()

Short description

Get the region perimeter length in world units. The length is computed as the sum of distances between individual pixels. Note that this means that the reported perimeters are different than the analytical perimeter for mathematical objects like circles and rectangles.

See also

Image.PixelRegion.getBorderRegion

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	Input region or region list
referenceImage	CONST_OBJECT Image	Reference image, used to define the image world coordinate system.

Return values
Name	Type	Description
perimeterLength	FLOAT	Computed perimeter length in world units (single value or list)

Sample

perimeterLength = Image.PixelRegion.getPerimeterLength(region, referenceImage)

getPrincipalAxes()

Short description

Get principal axes of the region (orientation and length of major/minor axes, derived from region moments).

Keywords

PCA, covariance, eccentricity, elongation, major, moment, minor

See also

Image.PixelRegion.getElongation

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	Input region
referenceImage	CONST_OBJECT Image	Reference image, defines the image world coordinate system.

Return values
Name	Type	Description
angleRad	FLOAT	Rotation angle of the major axis in radians.
majorAxisWorld	FLOAT	Length of the major axis in world units
minorAxisWorld	FLOAT	Length of the minor axis in world units

Sample

angleRad, majorAxisWorld, minorAxisWorld = Image.PixelRegion.getPrincipalAxes(region, referenceImage)

getStatistics()

Short description

Get pixel value statistics for pixels belonging to a pixel region. Image world coordinate system values are used and pixels with missing data are excluded. By default, the reference surface z=0 is used. Another reference surface (plane) may be provided, basing the statistics on deviations from that surface. If the statistics can not be calculated, nil is returned. A vector of regions can be provided, in which case four vectors of statistics are returned, one entry for each input region. Any invalid input region in the vector will have the corresponding output entries set to zero.

Keywords

average, max, maximum, min, minimum, standard deviation, std, mean

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	Input region, defines the region of image in which to gather statistics, or several regions where statistics are calculated individually for each region.
image	CONST_OBJECT Image	Input image, defines the image from which to get pixel value input.
referenceSurface	CONST_OBJECT Shape3D	Reference surface, defines the zero level in world coordinates. Default is the plane z=0.

Return values
Name	Type	Description
min	FLOAT	Minimal value, or vector of values with one entry for each region.
max	FLOAT	Maximal value, or vector of values with one entry for each region.
average	FLOAT	Average value, or vector of values with one entry for each region.
standardDeviation	FLOAT	Standard deviation, or vector of standard deviations with one entry for each region.

Sample

min, max, average, standardDeviation = Image.PixelRegion.getStatistics(region, image, referenceSurface)

getUnion()

Short description

Get the set union of two or more regions. If two regions are give, the function returns the set union of the two regions. If one list of regions is given, the function returns the set union of all regions in the list. If one list and one region is given, the function returns a list of regions containing the unions of each region in the list and the single region. If two lists are given, the function returns a vector of regions containing the pair-wise unions of the regions in the lists. The lists must be the same length.

Parameters
Name	Type	Description
region1	CONST_OBJECT Image.PixelRegion	First input region or list of regions
region2	CONST_OBJECT Image.PixelRegion	Second input region or list of regions

Return values
Name	Type	Description
outputRegion	OBJECT Image.PixelRegion	Resulting region or list of regions

Sample

outputRegion = Image.PixelRegion.getUnion(region1, region2)

getVolume()

Short description

Get the volume between a height map and a reference surface within the region or regions. Image world coordinate system values are used. By default, the reference surface z=0 is used. Another reference surface (plane) may be provided. NOTE: Values below the reference surface are disregarded (counted as a zero-volume-contribution). Pixels with missing data are disregarded (counted as a zero-volume-contribution). For other ways of handling missing data, such as filling using nearby data, call the appropriate Image.missingData-function before calling getVolume.

See also

Image.PixelRegion.getArea

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	Input region or region list.
heightMap	CONST_OBJECT Image	Input image that can be interpreted as a height map using the origin and pixelSize properties.
referenceSurface	CONST_OBJECT Shape3D	Reference surface, defines the zero level in world coordinates. Default is the plane z=0.

Return values
Name	Type	Description
volume	FLOAT	The volume contained below the height map within the input region (single value or list), or nil in case of failure.

Sample

volume = Image.PixelRegion.getVolume(region, heightMap)

intersectImage()

Short description

Get the part of a pixel region within a reference image.

Keywords

complement, difference

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	Input region or list of regions.
referenceImage	CONST_OBJECT Image	Reference image, defines the area for cropping the region.

Return values
Name	Type	Description
outputRegion	OBJECT Image.PixelRegion	The part of region or list of regions within referenceImage, or nil on error.

Sample

outputRegion = Image.PixelRegion.intersectImage(region, referenceImage)

invert()

Short description

Get the complement within a reference image, returns a pixel region(s) containing all reference image pixels not in the input region(s).

Keywords

complement

See also

Image.PixelRegion.intersectImage

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	Input region(s).
referenceImage	CONST_OBJECT Image	Reference image, defines the area for inverting the region(s).

Return values
Name	Type	Description
outputRegion	OBJECT Image.PixelRegion	The complement(s) to region(s) within referenceImage, or nil on error.

Sample

outputRegion = Image.PixelRegion.invert(region, referenceImage)

isEmpty()

Short description

Check if the region contains zero pixels. If a vector of pixel regions is provided the output is a vector of the same length.

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	Input pixel region. Can also be a vector of pixel regions.

Return values
Name	Type	Description
isEmpty	BOOL	True if the region is empty. Can also be a vector of booleans.

Sample

isEmpty = Image.PixelRegion.isEmpty(region)

thin()

Short description

Creates a skeleton region out of the input region.

Keywords

morphology, skeleton

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	Input region or list of regions.

Return values
Name	Type	Description
outputRegion	OBJECT Image.PixelRegion	Skeleton region

Sample

outputRegion = Image.PixelRegion.thin(region)

toImage()

Short description

Convert the region to an image, using a specified value for pixels within the region. The value is in world coordinates and is clamped to the representable range of the image.

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	Input region
referenceImage	CONST_OBJECT Image	Reference image, defines the size, pixel type and image world coordinate system of the output image.
valueWorld	FLOAT	World coordinate value to use within the region, default is 255

Return values
Name	Type	Description
outputImage	OBJECT Image	Image containing the region

Sample

outputImage = Image.PixelRegion.toImage(region, referenceImage, valueWorld)

toPoints2D()

Short description

Get a vector of the pixels contained in the region represented as 2D Point objects. Pixel coordinates are converted to image world coordinates using the reference image. Any parts of the input region that is outside the reference image bounds is ignored.

See also

Image.PixelRegion.toPoints3D, Point

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	The region to process
referenceImage	CONST_OBJECT Image	Reference image, defines the image world coordinate system

Return values
Name	Type	Description
points	OBJECT Point	Vector of 2D Point objects, expressed in image world coordinates, for each pixel contained within the region.

Sample

points = Image.PixelRegion.toPoints2D(region, referenceImage)

toPoints3D()

Short description

Get a vector of the pixels contained in the region represented as 3D Point objects, including a z value from the reference image. Any parts of the input region that is outside the image bounds or contains missing data is ignored.

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	The region to process
referenceImage	CONST_OBJECT Image	Input image, defines the pixel-world mapping and is used to get z values (pixel values converted using the z-part of the pixel-world mapping)

Return values
Name	Type	Description
points	OBJECT Point	Vector of 3D Point objects, expressed in image world coordinates, for each pixel contained within the region.

Sample

points = Image.PixelRegion.toPoints3D(region, referenceImage)

toString()

Short description

Get a brief string description of the pixel region. This is equal to the text shown in the debugger to describe the region. Can also be called with a vector of pixel regions.

Keywords

description, help, print

Parameters
Name	Type	Description
pixelRegion	CONST_OBJECT Image.PixelRegion	Input pixel region. Can also be a vector of pixel regions.

Return values
Name	Type	Description
str	STRING	Description of the region. If the input is a vector the output is a vector of strings.

Sample

print("Description: " .. Image.PixelRegion.toString(pixelRegion))

touchesImageBorder()

Short description

Returns true if a pixel region touches the border of provided image

Parameters
Name	Type	Description
region	CONST_OBJECT Image.PixelRegion	Input region or region list
referenceImage	CONST_OBJECT Image	Input image, used only to define the image size

Return values
Name	Type	Description
touches	BOOL	True if region touches image borders (single value or list)

Sample

outputRegion = Image.PixelRegion.touchesImageBorder(region, referenceImage)

transform()

Short description

Transform the region using a general 2D Transform object, expressed in image world coordinates.

See also

Image.transform

Parameters
Name	Type	Description
inputRegion	CONST_OBJECT Image.PixelRegion	Input region, or a list of regions
transform	CONST_OBJECT Transform	Transform to apply, expressed in world coordinates
referenceImage	CONST_OBJECT Image	Reference image, used to define the image world coordinate system

Return values
Name	Type	Description
outputRegion	OBJECT Image.PixelRegion	The transformed pixel region or region list

Sample

outputRegion = Image.PixelRegion.transform(region, transform, referenceImage)

Image.PixelRegion.Filter

Short description

Filter for pixel regions. Offers convenient filtering and sorting based on all features from Image.PixelRegion. The description of each filter contains a reference to the corresponding function.

Keywords

blobs, extraction, sorting, features

Overview

apply(), create(), setCondition(), setRange(), sortBy(), toString()

Functions

apply()

Short description

Apply the filter to a region list. Return the filtered and sorted regions. The actual regions are copied by reference, so changing a region in the input list makes the same region change also in the output list and vice versa. Note that lists in Lua are 1-indexed and matrices are 0-indexed, so the features corresponding to filteredRegions[i] is at row i-1 in the featureValues matrix. If no blobs are found, the function returns an empty filteredRegions list and no featureValues matrix.

Parameters
Name	Type	Description
filter	OBJECT Image.PixelRegion.Filter	Filter to apply
inputRegions	OBJECT Image.PixelRegion	Input regions
inputImage	OBJECT Image	Input image, used for pixel-world mapping and for pixel values if value statistics features are used (median, average, etc.)

Return values
Name	Type	Description
filteredRegions	OBJECT Image.PixelRegion	Filtered and sorted output regions
featureValues	OBJECT Matrix	Matrix of computed feature values. Each row corresponds to an output region and each column to a computed feature. The columns are in the same order as the features are mentioned in calls to setRange and setCondition before applying the filter.

Sample

filteredRegions, featureValues = Image.PixelRegion.Filter.apply(filter, inputRegions, inputImage)

create()

Short description

Create a new PixelRegion filter

Return values
Name	Type	Description
filter	OBJECT Image.PixelRegion.Filter	The new filter

Sample

filter = Image.PixelRegion.Filter.create()

setCondition()

Short description

Set a new equality/inequality condition to the filter. Only regions with feature value within the given range will be included in the filter output.

Keywords

inequal, equal

See also

Image.PixelRegion.Filter.setRange

Parameters
Name	Type	Description
filter	OBJECT Image.PixelRegion.Filter	Input filter to modify
featureType	ENUM FeatureType	The feature type that the filter applies to. Must be an integer feature type.
exactValue	INT	Exact value to compare to
equality	BOOL	Set to true for equality comparison and false for inequality. Default is equality.

Sample

Image.PixelRegion.Filter.setCondition(filter, "HOLESCOUNT", 0)

setRange()

Short description

Set a new range constraint to the filter. Only regions with feature value within the given range will be included in the filter output.

Keywords

interval

See also

Image.PixelRegion.Filter.setCondition

Parameters
Name	Type	Description
filter	OBJECT Image.PixelRegion.Filter	Input filter to modify
featureType	ENUM FeatureType	The feature type that the filter applies to
minValue	FLOAT	Minimum allowed value (inclusive)
maxValue	FLOAT	Maximum allowed value (inclusive)
withinRange	BOOL	Set to true to setup a within-range check and false for an outside-range check. Default is within-range.

Sample

Image.PixelRegion.Filter.setRange(filter, "CONVEXITY", 0.0, 0.8)

sortBy()

Short description

Defines which feature the output list shall be sorted by

Parameters
Name	Type	Description
filter	OBJECT Image.PixelRegion.Filter	Input filter to modify
featureType	ENUM FeatureType	The feature type to sort by
ascending	BOOL	Set to true to sort in ascending order (default), false for descending

Sample

Image.PixelRegion.Filter.sortBy(filter, "CENTROIDX")

toString()

Short description

Get a user-friendly string description of the filter

Parameters
Name	Type	Description
filter	OBJECT Image.PixelRegion.Filter	Input filter

Return values
Name	Type	Description
description	STRING	User-friendly description of the filter

Sample

print("The filter is: " .. Image.PixelRegion.Filter.toString(filter))

Image.Provider

Short description

Provides functionality to control and receive heightmap images from the camera of the programmable device.

Overview

Image.Provider.Camera

Short description

Provides functionality to control and receive images from the camera of the programmable device.

Overview

create(), deregister(), register(), setConfig(), start(), stop(), trigger()

OnNewImage

Functions

create()

Short description

Creates an instance of the image provider, which provides images asynchronously. Will return nil if there already exists a handle of this CROWN.

Return values
Name	Type	Description
handle	HANDLE	ImageProviderCam exists as long as this handle.

Sample

handle = Image.Provider.Camera.create()

deregister()

Short description

This function is used to deregister from any registered event of the handle.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
eventname	STRING	The event to deregister from
callback	STRING	The function name which was registered on the event

Return values
Name	Type	Description
success	BOOL	True if successfully deregistered. False if event does not exist or callback wasn’t registered.

register()

Short description

This function is used to register for any event of this provider. The event name is specified as parameter.

Parameters
Name	Type	Description
handle	HANDLE	Handle returned by create
eventname	STRING	The event to register to
callback	STRING	name of function to call upon the event

Return values
Name	Type	Description
success	BOOL	True if successfully registered. False if event does not exist.

Sample

Image.Provider.Camera.register(handle, "OnNewImage", "HandleNewImage")

setConfig()

Short description

Applies the given configuration to the camera provider. Can cause minor errors if called during active image acquisition.

Parameters
Name	Type	Description
handle	HANDLE	Instance handle of the Camera provider.
configHandle	HANDLE	Handle of config instance to apply.

Return values
Name	Type	Description
success	BOOL	true if new value could be set in configuration

Sample

Image.Provider.Camera.setConfig(camHandle, configHandle)

start()

Short description

Triggers the camera to start taking images explicitly.

Parameters
Name	Type	Description
handle	HANDLE	Handle returned by create

Return values
Name	Type	Description
success	BOOL	True if call to start succeeded and image acquisition was started.

Sample

Image.Provider.Camera.start(handle)

stop()

Short description

Stops taking images explicitly.

Parameters
Name	Type	Description
handle	HANDLE	Handle returned by create

Sample

Image.Provider.Camera.stop(handle)

trigger()

Short description

Trigger images explicitly. Image trigger mode must be set to "SOFTWARE" by Image.Provider.Camera.V3TConfig3D.setImageTriggerMode().

Parameters
Name	Type	Description
handle	HANDLE	The instance to use
abortOngoing	BOOL	If true any ongoing image acquisition is aborted before triggering. Default set to false

Return values
Name	Type	Description
success	BOOL	Returns true if function call was successful, otherwise false

Sample

Image.Provider.Camera.trigger(handle, true)

Events

OnNewImage

Short description

The image event which is thrown for every image.

Parameters
Name	Type	Description
handle	HANDLE	Handle returned by create
image	OBJECT Image	the captured image
sensorData	OBJECT SensorData	additional data belonging to the image

Image.Provider.Camera.V3TConfig2D

Short description

Configuration for acquiring 2D sensor images. The sensor image is useful for viewing the apperance of the laser while configuring exposure and gain. Sensor images can also be used for 2D image analysis after disabling the laser with TriSpector.setLaserEnabled(false). Call Image.Provider.Camera.setConfig() with a V3TConfig2D to activate sensor image acquisition.

Overview

create(), getExposureTime(), getGain(), getImageTriggerMode(), getSensorRegion(), setExposureTime(), setGain(), setImageTriggerMode(), setSensorRegion(), validate()

Functions

create()

Short description

Creates an instance of a V3TConfig2D.

Return values
Name	Type	Description
handle	HANDLE	Handle to the new instance.

Sample

handle = Image.Provider.Camera.V3TConfig2D.create()

getExposureTime()

Short description

Get exposure time

Parameters
Name	Type	Description
handle	HANDLE	The instance to use

Return values
Name	Type	Description
exposureTime	INT	Returns configured exposure time in microseconds

Sample

exposureTime = Image.Provider.Camera.V3TConfig2D.getExposureTime(handle)

getGain()

Short description

Get gain

Parameters
Name	Type	Description
handle	HANDLE	The instance to use

Return values
Name	Type	Description
gain	FLOAT	Returns configured gain

Sample

gain = Image.Provider.Camera.V3TConfig2D.getGain(handle)

getImageTriggerMode()

Short description

Get image trigger mode

Parameters
Name	Type	Description
handle	HANDLE	The instance to use

Return values
Name	Type	Description
imageTriggerMode	ENUM ImageTriggerMode	Returns configured image trigger mode

Sample

imageTriggerMode = Image.Provider.Camera.V3TConfig2D.getImageTriggerMode(handle)

getSensorRegion()

Short description

Get sensor region

Parameters
Name	Type	Description
handle	HANDLE	The instance to use

Return values
Name	Type	Description
width	INT	Width in pixels
height	INT	Height in pixels
xOffset	INT	X-offset in pixels
yOffset	INT	Y-offset in pixels

Sample

width, height, xOffset, yOffset = Image.Provider.Camera.V3TConfig2D.getSensorRegion(handle)

setExposureTime()

Short description

Set exposure time

Parameters
Name	Type	Description
handle	HANDLE	The instance to use
exposureTime	INT	Exposure time in microseconds. Allowed range [1, 100000]

Return values
Name	Type	Description
success	BOOL	Returns true if function call was successful, otherwise false

Sample

Image.Provider.Camera.V3TConfig2D.setExposureTime(handle, 50)

setGain()

Short description

Set gain

Parameters
Name	Type	Description
handle	HANDLE	The instance to use
gain	FLOAT	Gain. Allowed range [1, 8]

Return values
Name	Type	Description
success	BOOL	Returns true if function call was successful, otherwise false

Sample

Image.Provider.Camera.V3TConfig2D.setGain(handle, 2.0)

setImageTriggerMode()

Short description

Determines how sensor images are triggered.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use
imageTriggerMode	ENUM ImageTriggerMode	Image trigger mode

Return values
Name	Type	Description
success	BOOL	Returns true if function call was successful, otherwise false

Sample

Image.Provider.Camera.V3TConfig2D.setImageTriggerMode(handle, "SOFTWARE")

setSensorRegion()

Short description

Set the region on the image sensor to use when acquiring 2D-images.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use
width	INT	Width in pixels. Allowed range [64, 1280]
height	INT	Height in pixels. Allowed range [24, 1024]
xOffset	INT	X-offset in pixels. Allowed range [0, 1280 - width]
yOffset	INT	Y-offset in pixels. Allowed range [0, 1024 - height]

Return values
Name	Type	Description
success	BOOL	Returns true if function call was successful, otherwise false

Sample

Image.Provider.Camera.V3TConfig2D.setSensorRegion(handle, 1280, 1024, 0, 0)

validate()

Short description

Validate the configuration settings of this V3TConfig2D. This allows testing the validity of a V3TConfig2D without setting it to a provider. Note that Image.Provider.Camera.setConfig rejects invalid instances.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use

Return values
Name	Type	Description
validConfig	BOOL	Returns true if the configuration settings are valid, otherwise false

Sample

valid = Image.Provider.Camera.V3TConfig2D.validate(handle)

Image.Provider.Camera.V3TConfig3D

Short description

Configuration for acquiring heightmaps. Call Image.Provider.Camera.setConfig() with a V3TConfig3D to activate heightmap acquisition.

Functions

create()

Short description

Creates an instance of a V3TConfig3D.

Return values
Name	Type	Description
handle	HANDLE	Handle to the new instance.

Sample

handle = Image.Provider.Camera.V3TConfig3D.create()

get2DConfig()

Short description

Get a V3TConfig2D with the sensor settings from this V3TConfig3D. The V3TConfig2D can be used to acquire 2D sensor images for inspecting the appearance of the laser line. The V3TConfig2D sensor region is determined by the V3TConfig3D field of view.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use

Return values
Name	Type	Description
configHandle	HANDLE	Handle of a 2D config instance

Sample

config = Image.Provider.Camera.V3TConfig3D.get2DConfig(handle)

getEncoderTicksPerMm()

Short description

Get the configured number of encoder ticks per mm. A tick is defined as a complete cycle of an encoder channel.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use

Return values
Name	Type	Description
ticksPerMm	FLOAT	Returns configured encoder ticks per mm

Sample

ticksPerMm = Image.Provider.Camera.V3TConfig3D.getEncoderTicksPerMm(handle)

getExposureTime()

Short description

Get the configured exposure time.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use

Return values
Name	Type	Description
exposureTime	INT	Returns configured exposure time in microseconds

Sample

exposureTime = Image.Provider.Camera.V3TConfig3D.getExposureTime(handle)

getExposureTimeLimits()

Short description

Get the current limits for setExposureTime. The upper limit depends on the field of view size.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use

Return values
Name	Type	Description
min	INT	Minimum possible exposure time
max	INT	Maximum possible exposure time

Sample

min, max = Image.Provider.Camera.V3TConfig3D.getExposureTimeLimits(handle)

getFieldOfView()

Short description

Get the configured field of view.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use

Return values
Name	Type	Description
width	FLOAT	Width in mm
height	FLOAT	Height in mm
xOffset	FLOAT	X-offset in mm for the field of view center relative to the guaranteed field of view center.
zOffset	FLOAT	Z-offset in mm for the field of view center relative to the guaranteed field of view center.

Sample

width, height, xOffset, zOffset = Image.Provider.Camera.V3TConfig3D.getFieldOfView(handle)

getFreeRunningSpeed()

Short description

Get the configured movement speed for free running profile trigger mode.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use

Return values
Name	Type	Description
freeRunningSpeed	FLOAT	Returns configured motion speed for free running mode in mm/s

Sample

speed = Image.Provider.Camera.V3TConfig3D.getFreeRunningSpeed(handle)

getFreeRunningSpeedLimits()

Short description

Get the current limits for setFreeRunningSpeed. The upper limit depends on the profile distance, the field of view size and (in some cases) the exposure time.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use

Return values
Name	Type	Description
min	FLOAT	Minimum possible free running speed
max	FLOAT	Maximum possible free running speed

Sample

min, max = Image.Provider.Camera.V3TConfig3D.getFreeRunningSpeedLimits(handle)

getGain()

Short description

Get the configured image sensor gain.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use

Return values
Name	Type	Description
gain	FLOAT	Returns configured gain

Sample

gain = Image.Provider.Camera.V3TConfig3D.getGain(handle)

getGuaranteedFieldOfView()

Short description

Get the guaranteed field of view. Working within this field of view guarantees that the configuration can be moved to another TriSpectorP device of the same variant. Returns nil if an invalid device variant is specified.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use
deviceVariant	ENUM TriSpector.DeviceVariant	Device variant to get guaranteed Field Of View for. Defaults to the executing device’s variant if not specified

Return values
Name	Type	Description
lowerWidth	INT	Lower width in mm
upperWidth	INT	Upper width in mm
height	INT	Height in mm
xOffset	INT	X-offset in mm
zOffset	INT	Z-offset in mm

Sample

lowerWidth, upperWidth, height, xOffset, zOffset = Image.Provider.Camera.V3TConfig3D.getGuaranteedFieldOfView(handle)

getHeightmapLength()

Short description

Get the configured heightmap length.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use

Return values
Name	Type	Description
length	FLOAT	Length in mm

Sample

length = Image.Provider.Camera.V3TConfig3D.getHeightmapLength(handle)

getHeightmapLengthLimits()

Short description

Get the current limits for setHeightmapLength. A heightmap must contain at least 16 and at most 2500 profiles. The number of profiles is determined by the heightmap length divided by the profile distance.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use

Return values
Name	Type	Description
min	FLOAT	Minimum possible heightmap length in mm
max	FLOAT	Maximum possible heightmap length in mm

Sample

min, max = Image.Provider.Camera.V3TConfig3D.getHeightmapLengthLimits(handle)

getImageTriggerDelay()

Short description

Get the configured image trigger delay value and unit

Parameters
Name	Type	Description
handle	HANDLE	The instance to use

Return values
Name	Type	Description
delay	INT	Returns configured image trigger delay value
unit	ENUM ImageTriggerDelayUnit	Returns configured image trigger delay unit

Sample

delay, unit = Image.Provider.Camera.V3TConfig3D.getImageTriggerDelay(handle)

getImageTriggerMode()

Short description

Get image trigger mode

Parameters
Name	Type	Description
handle	HANDLE	The instance to use

Return values
Name	Type	Description
imageTriggerMode	ENUM ImageTriggerMode	Returns configured image trigger mode

Sample

imageTriggerMode = Image.Provider.Camera.V3TConfig3D.getImageTriggerMode(handle)

getLaserThreshold()

Short description

Get the configured laser threshold. Sensor image intensities above this threshold will be included when locating the laser peak.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use

Return values
Name	Type	Description
laserThreshold	INT	Returns configured laser threshold

Sample

laserThreshold = Image.Provider.Camera.V3TConfig3D.getLaserThreshold(handle)

getObjectTriggerLine()

Short description

Return the line used for object triggering.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use

Return values
Name	Type	Description
line	OBJECT Shape3D	3D line segment. The line used in Object Trigger.
threshold	INT

Sample

line, threshold = Image.Provider.Camera.V3TConfig3D.getObjectTriggerLine(handle)

getPeakSelectionMode()

Short description

Get peak selection mode

Parameters
Name	Type	Description
handle	HANDLE	The instance to use

Return values
Name	Type	Description
peakSelectionMode	ENUM PeakSelectionMode	Returns configured peak selection mode

Sample

mode = Image.Provider.Camera.V3TConfig3D.getPeakSelectionMode(handle)

getProfileDistance()

Short description

Get the configured distance in mm between consecutive profiles in the heightmap. Note that this is the value as specified with setProfileDistance which may differ from the actual value when using an encoder.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use

Return values
Name	Type	Description
profileDistance	FLOAT	Returns configured distance in mm between consecutive profiles

Sample

profileDistance = Image.Provider.Camera.V3TConfig3D.getProfileDistance(handle)

getProfileDistanceLimits()

Short description

Get the current limits for setProfileDistance. Using an encoder (ProfileTriggerMode "ENCODER"), the limits depend on the heightmap length. In free running mode the limits also depend on the free running speed, field of view size and (in some cases) the exposure time.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use

Return values
Name	Type	Description
min	FLOAT	Minimum possible profile distance
max	FLOAT	Maximum possible profile distance

Sample

min, max = Image.Provider.Camera.V3TConfig3D.getProfileDistanceLimits(handle)

getProfileTriggerMode()

Short description

Get profile trigger mode

Parameters
Name	Type	Description
handle	HANDLE	The instance to use

Return values
Name	Type	Description
profileTriggerMode	ENUM ProfileTriggerMode	Returns current profile trigger mode

Sample

profileTriggerMode = Image.Provider.Camera.V3TConfig3D.getProfileTriggerMode(handle)

getXResolution()

Short description

Get the configured X-resolution

Parameters
Name	Type	Description
handle	HANDLE	The instance to use

Return values
Name	Type	Description
xResolution	FLOAT	Returns configured X-resolution in mm/px

Sample

xResolution = Image.Provider.Camera.V3TConfig3D.getXResolution(handle)

getXResolutionLimits()

Short description

Get the current limits for setXResolution. The limits depend on the field of view width.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use

Return values
Name	Type	Description
min	FLOAT	Minimum possible x-resolution
max	FLOAT	Maximum possible x-resolution

Sample

min, max = Image.Provider.Camera.V3TConfig3D.getXResolutionLimits(handle)

setEncoderTicksPerMm()

Short description

Specify the number of ticks that are given by the encoder per mm. A tick is defined as a complete cycle of an encoder channel.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use
ticksPerMm	FLOAT	Encoder ticks per mm. Allowed range [1, 10000]

Return values
Name	Type	Description
success	BOOL	Returns true if function call was successful, otherwise false

Sample

Image.Provider.Camera.V3TConfig3D.setEncoderTicksPerMm(handle, 58)

setExposureTime()

Short description

Set the exposure time for the image sensor. With optimal exposure time the laser appears as a gray line in sensor images. If the exposure is too high, the reflectance image will be saturated.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use
exposureTime	INT	Exposure time in microseconds. Allowed range [1, 100000]

Return values
Name	Type	Description
success	BOOL	Returns true if function call was successful, otherwise false

Sample

Image.Provider.Camera.V3TConfig3D.setExposureTime(handle, 50)

setFieldOfView()

Short description

Set the field of view rectangle. Data outside the rectangle is excluded from heightmap profiles. A smaller field of view can allow a shorter profile distance or higher speed.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use
width	FLOAT	Width in mm
height	FLOAT	Height in mm
xOffset	FLOAT	X-offset in mm for the field of view center relative to the guaranteed field of view center.
zOffset	FLOAT	Z-offset in mm for the field of view center relative to the guaranteed field of view center.

Return values
Name	Type	Description
success	BOOL	Returns true if function call was successful, otherwise false

Sample

Image.Provider.Camera.V3TConfig3D.setFieldOfView(handle, 200, 400, 0, 200)

setFreeRunningSpeed()

Short description

Set the movement speed of the object (or TriSpectorP device) for free running profile trigger mode. This is used with setProfileTriggerMode("FREE_RUNNING").

Parameters
Name	Type	Description
handle	HANDLE	The instance to use
freeRunningSpeed	FLOAT	Speed in mm/s. Allowed range [1.0, 5000.0]

Return values
Name	Type	Description
success	BOOL	Returns true if function call was successful, otherwise false

Sample

Image.Provider.Camera.V3TConfig3D.setFreeRunningSpeed(handle, 1000.0)

setGain()

Short description

Set the image sensor gain. Note that adjusting the exposure with setExposureTime is preferred over gain when possible, as gain increases noise in images.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use
gain	FLOAT	Gain. Allowed range [1, 8]

Return values
Name	Type	Description
success	BOOL	Returns true if function call was successful, otherwise false

Sample

Image.Provider.Camera.V3TConfig3D.setGain(handle, 2.0)

setHeightmapFinishedOutput()

Short description

Digital output that will be activated when a heightmap acquisition is completed. The given output is activated when the last profile of a heightmap is acquired. This can be used to synchronize the image acquisition with an external device. The output will remain active for the duration of the activation value configured in the Connector.DigitalOut.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use
output	AUTO	A Connector.DigitalOut instance or nil

Return values
Name	Type	Description
success	BOOL	Returns true if function call was successful, otherwise false.

Sample

Image.Provider.Camera.V3TConfig3D.setHeightmapFinishedOutput(handle, do4)

setHeightmapLength()

Short description

Set the heightmap length in mm. The length and profile distance determines the number of profiles in a heightmap.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use
length	FLOAT	Length in mm

Return values
Name	Type	Description
success	BOOL	Returns true if function call was successful, otherwise false.

Sample

Image.Provider.Camera.V3TConfig3D.setHeightmapLength(handle, 300)

setImageTriggerDelay()

Short description

Set the image trigger delay in either ms or mm. Heightmap acquisition is delayed by the configured time or distance after triggering.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use
delay	INT	Image trigger delay value. Allowed range [0,10000]
unit	ENUM ImageTriggerDelayUnit	Unit for the specified delay value

Return values
Name	Type	Description
success	BOOL	Returns true if function call was successful, otherwise false

Sample

Image.Provider.Camera.V3TConfig3D.setImageTriggerDelay(handle, 15, "MM")

setImageTriggerMode()

Short description

Set image trigger mode. This determines how heightmap images are triggered.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use
imageTriggerMode	ENUM ImageTriggerMode	Image trigger mode

Return values
Name	Type	Description
success	BOOL	Returns true if function call was successful, otherwise false

Sample

Image.Provider.Camera.V3TConfig3D.setImageTriggerMode(handle, "OBJECT")

setLaserThreshold()

Short description

Set laser threshold. Sensor image intensities above this threshold will be included when locating the laser peak. A high threshold value reduces noise in the resulting heightmap, while a low threshold makes it possible to detect weak laser peaks.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use
laserThreshold	INT	Laser threshold. Allowed range [0, 255]

Return values
Name	Type	Description
success	BOOL	Returns true if function call was successful, otherwise false

Sample

Image.Provider.Camera.V3TConfig3D.setLaserThreshold(handle, 50)

setObjectTriggerLine()

Short description

Specify a line and threshold for ImageTriggerMode "OBJECT". A heightmap acquisition is triggered if the amount of data extending above the line is greater than threshold.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use
line	OBJECT Shape3D	3D line segment. The line must be specified in the XZ plane so Y-coordinates should be set to 0.
threshold	INT	Threshold in percent how much data should be above

Return values
Name	Type	Description
success	BOOL	Returns true if function call was successful, otherwise false

Sample

Image.Provider.Camera.V3TConfig3D.setObjectTriggerLine(handle, line, 20)

setPeakSelectionMode()

Short description

Set the peak selection mode. This determines how the laser line is detected and can help for handling reflections.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use
peakSelectionMode	ENUM PeakSelectionMode	Peak selection mode

Return values
Name	Type	Description
success	BOOL	Returns true if function call was successful, otherwise false

Sample

Image.Provider.Camera.V3TConfig3D.setPeakSelectionMode(handle, "STRONGEST")

setProfileDistance()

Short description

Set distance in mm between consecutive profiles in the heightmap. Note that when the profileTriggerMode is set to ENCODER the actual value for profileDistance might be slightly adjusted since the number of encoder ticks between two profiles is rounded to the nearest integer.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use
profileDistance	FLOAT	Distance in mm between consecutive profiles. Allowed range [0.01,10]

Return values
Name	Type	Description
success	BOOL	Returns true if function call was successful, otherwise false

Sample

Image.Provider.Camera.V3TConfig3D.setProfileDistance(handle, 2.0)

setProfileTriggerMode()

Short description

Set whether heightmap profiles are triggered at fixed intervals (time) or by encoder ticks (distance).

Parameters
Name	Type	Description
handle	HANDLE	The instance to use
profileTriggerMode	ENUM ProfileTriggerMode	Profile trigger mode

Return values
Name	Type	Description
success	BOOL	Returns true if function call was successful, otherwise false

Sample

Image.Provider.Camera.V3TConfig3D.setProfileTriggerMode(handle, "FREE_RUNNING")

setXResolution()

Short description

Set the heightmap X-resolution in mm/pixel. To improve handling of rotated objects, set the x-resolution equal to the profile distance (square pixels).

Parameters
Name	Type	Description
handle	HANDLE	The instance to use
xResolution	FLOAT	X-resolution in mm/px

Return values
Name	Type	Description
success	BOOL	Returns true if function call was successful, otherwise false

Sample

Image.Provider.Camera.V3TConfig3D.setXResolution(handle, 0.8)

validate()

Short description

Validate the configuration settings of this V3TConfig3D. This allows testing the validity of a V3TConfig3D without setting it to a provider. Note that Image.Provider.Camera.setConfig rejects invalid instances.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use

Return values
Name	Type	Description
validConfig	BOOL	Returns true if the configuration settings are valid, otherwise false

Sample

valid = Image.Provider.Camera.V3TConfig3D.validate(handle)

Image.Provider.Directory

Short description

Image provider which provides images periodically from the filesystem. Images can be in format PNG or BMP.

Overview

create(), deregister(), register(), setAutoDeleteActive(), setCycleTime(), setCyclicModeActive(), setImagePoolSizeMB(), setPath(), start(), stop()

OnNewImage

Functions

create()

Short description

Creates an instance of the image directory provider, which provides images asynchronously from file-system.

Return values
Name	Type	Description
handle	HANDLE	Image provider exists as long as this handle exists.

Sample

dirProv = Image.Provider.Directory.create()

deregister()

Short description

This function is used to deregister from any registered event of the handle.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
eventname	STRING	The event to deregister from
callback	STRING	The function name which was registered on the event

Return values
Name	Type	Description
success	BOOL	True if successfully deregistered. False if event does not exist or callback wasn’t registered.

register()

Short description

This function is used to register for any event of the image provider. The event name is specified as parameter.

Parameters
Name	Type	Description
handle	HANDLE	Instance handle of this provider
eventname	STRING	The event to register to
callback	STRING	function name to call on the event

Return values
Name	Type	Description
success	BOOL	True if successfully registered. False if event does not exist.

Sample

Image.Provider.Directory.register(dirProv, "OnNewImage", "handleNewImage")

setAutoDeleteActive()

Short description

Sets auto-delete active. This means the image is deleted from the directory after load. Default is false.

Parameters
Name	Type	Description
handle	HANDLE	Instance handle of this provider
state	BOOL	If true the image file will be deleted after being loaded.

Sample

Image.Provider.Directory.setAutoDeleteActive(dirProv, true)

setCycleTime()

Short description

Sets the pause between taking images in milli seconds.

Parameters
Name	Type	Description
handle	HANDLE	Instance handle of this provider
periodMs	INT	Period in [ms] between images.

Sample

Image.Provider.Directory.setCycleTime(handle, 500)

setCyclicModeActive()

Short description

Sets cyclic-mode active. Default is true.

Parameters
Name	Type	Description
handle	HANDLE	Instance handle of this provider
state	BOOL	If false driver stops taking images if end of directory is reached.

Sample

Image.Provider.Directory.setCyclicModeActive(dirProv, true)

setImagePoolSizeMB()

Short description

Limits the number of mega bytes which can be acquired by capturing images and used at the same time. Default is 20.

Parameters
Name	Type	Description
handle	HANDLE	Instance handle of the provider.
size	INT	Size of the internal image pool in mega byte.

Sample

Image.Provider.Directory.setImagePoolSizeMB(cam, 20)

setPath()

Short description

Sets the directory and file extension(s) for the image provider from which it reads images.

Parameters
Name	Type	Description
handle	HANDLE	Instance handle of this provider
path	STRING	Path to the file-system
fileextensions	STRING	Supported file extensions (comma separated).
recursive	BOOL	An optional flag whether to run through subdriectories also.

Sample

Image.Provider.Directory.setPath(dirProv, ImageInputPath)

start()

Short description

Starts taking images.

Parameters
Name	Type	Description
handle	HANDLE	Instance handle of this provider
burst	INT	Leave empty or '0' for continuous acquisition. >0:=enable burst-mode with provided number of images.

Return values
Name	Type	Description
success	BOOL	Returns true if function call was successful, otherwise false

Sample

local success = Image.Provider.Directory.start(dirProv)

stop()

Short description

Stops taking images.

Parameters
Name	Type	Description
handle	HANDLE	Instance handle of this provider

Return values
Name	Type	Description
success	BOOL	Returns true if function call was successful, otherwise false

Sample

local stopped = Image.Provider.Directory.stop(dirProv)

Events

OnNewImage

Short description

The image event which is thrown for every new image.

Parameters
Name	Type	Description
handle	HANDLE	Instance handle of this provider
image	OBJECT Image	The loaded image
sensorData	OBJECT SensorData	Supplementary data which belongs to the image

Image.Pyramid

Short description

A multiscale representation of an image. Each level in the pyramid contains an image that is downsampled a factor 2 relative to the preceding level. Level 0 of the ImagePyramid keeps the original image. There are two smoothing operators that can be used to avoid aliasing artifacts in the downsampled images: "LINEAR" and "GAUSSIAN". The default method is "LINEAR". A non-interpolating nearest neighbor method is also available, "NEAREST". The coarsest level cannot contain an image smaller than 16x16 pixels, levels below this size are not created even if more levels are specified upon ImagePyramid creation. For odd-sized images, the output size after downscaling is different for the "LINEAR" and "GAUSSIAN" cases: if the size N is odd, the output size is (N-1)/2 for "LINEAR" and "NEAREST" while it is (N+1)/2 for "GAUSSIAN". Image world coordinate system handling: The coordinate system of the output image will be slightly adjusted in relation to the input to take into account pixel size changes. Eg. both the origin and pixel size of the image will typically change. World positions in the image should be retained such that for example overlay graphics can remain on the same position when plotted on different pyramid levels. Values in z, both origin and pixel size, are copied directly from the input image. Missing data handling: When using "LINEAR" or "NEAREST" as the DownsamplingMethod missing data is handled. For linear interpolation, missing data will remain if all points in the interpolation neighborhood are missing. Otherwise the missing data value will be ignored and the output will be the linear interpolation of the valid neighbors. DownsamplingMethod "GAUSSIAN", currently does not support missing data. Hardware acceleration: Some devices have FPGA-support for the pyramid generation. It is possible to switch between the CPU and FPGA versions using the setProcessingUnit()-function. Please note that if the FPGA accelerator is busy the processing will fall-back to CPU processing. The processing may also fall-back to CPU for some unsupported configurations. The rounding done in the CPU and the FPGA version may differ slightly resulting in different values in the least significant bit of the generated pyramid levels.

Keywords

decimate, downsample, resample, scalespace, subsample, scale

Overview

create(), generate(), getImage(), getLevelCount(), getProcessingUnit(), resize(), setProcessingUnit(), toString()

Functions

create()

Short description

Create an image pyramid. If no arguments are given an unintialized pyramid will be created, which can be populated at a later stage using the Image.Pyramid.generate() function.

Parameters
Name	Type	Description
image	CONST_OBJECT Image	Optional: Source image. Supported image types depends on used device type.
levelCount	INT	Optional: Desired number of pyramid levels. One level will be used for the original image, so to get at least one downscaled version the levelCount parameter must be larger than 1. Note that the created ImagePyramid may contain fewer levels as the coarsest level is limited to a side of minimum 16 pixels.
method	ENUM DownsamplingMethod	Optional: The downsampling method, currently NEAREST, LINEAR or GAUSSIAN are available. Default is LINEAR.
processingUnit	ENUM ProcessingUnit	Optional: Processing Unit to use (CPU, FPGA). Default is CPU.
cloneData	BOOL	Optional: If set to true a cloned copy of the original input image is made in the pyramid object. If set to false a reference copy is made, which saves execution time and memory. Note however, any other change made later to the input image will then also affect the pyramid object. Default is true, i.e., to make a cloned copy.

Return values
Name	Type	Description
pyramidImage	OBJECT Image.Pyramid	The created image pyramid.

Sample

pyramidImage = Image.Pyramid.create(image, levelCount, "LINEAR", "CPU")

generate()

Short description

Generate pyramid levels for an existing image pyramid, replacing any existing data in the pyramid object. The function works inplace, i.e., the object is modified directly.

Parameters
Name	Type	Description
pyramidImage	OBJECT Image.Pyramid	The image pyramid.
image	CONST_OBJECT Image	Source image. Supported image types depends on used device type.
levelCount	INT	Desired number of pyramid levels. One level will be used for the original image, so to get at least one downscaled version the levelCount parameter must be larger than 1. Note that the created ImagePyramid may contain fewer levels as the coarsest level is limited to a side of minimum 16 pixels.
method	ENUM DownsamplingMethod	The downsampling method, currently NEAREST, LINEAR or GAUSSIAN are available. Default is LINEAR.
processingUnit	ENUM ProcessingUnit	Optional: Processing Unit to use (CPU, FPGA). Default is CPU.
cloneData	BOOL	Optional: If set to true a cloned copy of the original input image is made in the pyramid object. If set to false a reference copy is made, which saves execution time and memory. Note however, any other change made later to the input image will then also affect the pyramid object. Default is true, i.e., to make a cloned copy.

Return values
Name	Type	Description
pyramidImage	OBJECT Image.Pyramid	Reference to the pyramid with generated pyramid levels, or nil if something goes wrong. Note that the function works inplace, modifying the object directly, the output is mainly for error checking.

Sample

pyramidImage = Image.Pyramid.generate(pyramidImage, image, levelCount, "LINEAR", "CPU")

getImage()

Short description

Get the image at the specified pyramid level. 0 is the 'finest' level i.e. the original image. The return image is a deep copy of the level image

Parameters
Name	Type	Description
pyramidImage	CONST_OBJECT Image.Pyramid	The image pyramid.
level	INT	The pyramid level to grab the image from.

Return values
Name	Type	Description
image	OBJECT Image	The image at the specified pyramid level.

Sample

image = Image.Pyramid.getImage(pyramidImage, levelCount)

getLevelCount()

Short description

Get the number of pyramid levels.

Parameters
Name	Type	Description
pyramidImage	CONST_OBJECT Image.Pyramid	The image pyramid.

Return values
Name	Type	Description
levelCount	INT	The number of pyramid levels.

Sample

levelCount = Image.Pyramid.getLevelCount(pyramidImage)

getProcessingUnit()

Short description

Get configured processing unit.

Parameters
Name	Type	Description
pyramidImage	OBJECT Image.Pyramid	The image pyramid.

Return values
Name	Type	Description
processingUnit	ENUM ProcessingUnit	Processing Unit to use (CPU, FPGA).

Sample

processingUnit = Image.Pyramid.getProcessingUnit(pyramidImage)

resize()

Short description

Resizes an existing image pyramid in terms of the number of pyramid levels, i.e., the pyramid is extendend with more levels or levels are removed. The pyramid is updated inplace.

Keywords

cut, remove, extend

See also

Image.Pyramid.generate

Parameters
Name	Type	Description
pyramidImage	OBJECT Image.Pyramid	The image pyramid.
levelCount	INT	The new number of pyramid levels. One level will be used for the original image, so to get at least one downscaled version the levelCount parameter must be larger than 1. Note that the created ImagePyramid may contain fewer levels as the coarsest level is limited to a side of max 16 pixels.

Return values
Name	Type	Description
pyramidImage	OBJECT Image.Pyramid	Reference to the resized pyramid, or nil if something goes wrong. Note that the function works inplace, modifying the object directly, the output is mainly for error checking.

Sample

pyramidImage = Image.Pyramid.resize(pyramidImage, levelCount)

setProcessingUnit()

Short description

Set processing unit to use for pyramid generation.

Parameters
Name	Type	Description
pyramidImage	OBJECT Image.Pyramid	The image pyramid.
processingUnit	ENUM ProcessingUnit	Processing Unit to use (CPU, FPGA).

Return values
Name	Type	Description
success	BOOL	True if set was successful.

Sample

success = Image.Pyramid.setProcessingUnit(pyramidImage, "CPU")

toString()

Short description

Get a brief string description of the image pyramid. This is equal to the text shown in the debugger to describe the image pyramid.

Parameters
Name	Type	Description
pyramidImage	CONST_OBJECT Image.Pyramid	The image pyramid.

Return values
Name	Type	Description
string	STRING	Description of the image pyramid

Sample

print("Description: " .. Image.Pyramid.toString(pyramidImage))

Image.ShapeFitter

Short description

This is a tool for fitting geometrical object like lines, circles and ellipses to edges and contours in an image. For grayscale images, the geometrical objects are fitted to transitions between dark and bright image contents. For heightmaps, they are fitted to transitions between low and high z values. To get started, create a ShapeFitter with the create function and then call fitLine, fitCircle or fitEllipse to adjust a line, circle or ellipse to fit to the image data. These are primarily intended for intensity images, however images with missing data are supported. For height maps, the function fitLine3D fits a 3D line to edges in the height map. For more detailed control of the fitting behavior, call the set functions before calling the fit function. The shape fitting procedure consists of the following steps: - A number of probe lines are created along the search region. An edge point is found on each probe line. - The geometrical object that best fits to the detected edge points is returned.

Keywords

RANSAC, contour, edges, least squares, model, fitting

Overview

create(), fitArc(), fitCircle(), fitCircle3D(), fitEllipse(), fitLine(), fitLine3D(), getEdgePoints(), getEdgePoints3D(), setDifferenceStep(), setFitMode(), setInterpolation(), setIterations(), setOutlierMargin(), setPolarity(), setProbeCount(), setSelection(), setSide(), setThreshold()

Functions

create()

Short description

Create a shape fitter with default settings.

Return values
Name	Type	Description
shapeFitter	HANDLE	Created shape fitter.

Sample

shapeFitter = Image.ShapeFitter.create()

fitArc()

Short description

Fit a circular arc using the current settings within a search region defined by a shape sector. The angular extent of the fitted arc is copied from the search sector. Image world coordinate system handling: The arc is fitted in world coordinates. Missing data handling: Pixels with missing data are ignored, the arc is only fitted to valid data.

Parameters
Name	Type	Description
shapeFitter	HANDLE	Shape fitter to use.
image	CONST_OBJECT Image	Input image.
searchSector	CONST_OBJECT Shape	Search region, defining the search region center, inner and outer radii, and the angles that limit the sector.

Return values
Name	Type	Description
arc	OBJECT Shape	Fitted arc.
quality	FLOAT	Vector with fitting quality measurements [meanError, inlierRate, edgePointRate], where meanError is the average fitting error of inlier points in world coordinates, inlierRate is the rate of input points that were used to fit the final circle and edgePointRate is the rate of edge probes where an edge point was found. For the least squares method, all points are used and the inlier rate is always 100%.

Sample

arc, quality = Image.ShapeFitter.fitArc(shapeFitter, image, searchSector)

fitCircle()

Short description

Fit a circle using the current settings within a search region defined by two concentric circles. Image world coordinate system handling: The circle is fitted in world coordinates. Missing data handling: Pixels with missing data are ignored, the circle is only fitted to valid data.

See also

Image.ShapeFitter.fitEllipse

Parameters
Name	Type	Description
shapeFitter	HANDLE	Shape fitter to use.
image	CONST_OBJECT Image	Input image.
outerCircle	CONST_OBJECT Shape	Outer circle of the search region, defining the search region center and outer radius of the search region.
innerRadius	FLOAT	Inner radius of the search region.

Return values
Name	Type	Description
circle	OBJECT Shape	Fitted circle.
quality	FLOAT	Vector with fitting quality measurements [meanError, inlierRate, edgePointRate], where meanError is the average fitting error of inlier points in world coordinates, inlierRate is the rate of input points that were used to fit the final circle and edgePointRate is the rate of edge probes where an edge point was found. For the least squares method, all points are used and the inlier rate is always 100%.

Sample

circle, quality = Image.ShapeFitter.fitCircle(shapeFitter, image, outerCircle, innerRadius)

fitCircle3D()

Short description

Fit a circle in 3D using the current settings. In addition to the xy-region defined by the outerCircle and the innerRadius, the zBounds parameter allows limiting the edge point search space in height. Image world coordinate system handling: The circle is fitted in world coordinates. Missing data handling: Pixels with missing data are ignored, the circle is only fitted to valid data.

Parameters
Name	Type	Description
shapeFitter	HANDLE	Shape fitter to use.
image	CONST_OBJECT Image	Input image.
outerCircle	CONST_OBJECT Shape	Outer circle of the search region, defining the search region center and outer radius of the search region.
innerRadius	FLOAT	Inner radius of the search region.
zBounds	FLOAT	Two values providing the min and max z values where edges are searched for.

Return values
Name	Type	Description
circle	OBJECT Shape3D	Fitted circle.
quality	FLOAT	Vector with fitting quality measurements [meanError, inlierRate, edgePointRate], where meanError is the average fitting error of inlier points in world coordinates, inlierRate is the rate of input points that were used to fit the final line and edgePointRate is the rate of edge probes where an edge point was found. For the least squares method, all points are used and the inlier rate is always 100%.

Sample

circle, quality = Image.ShapeFitter.fitCircle3D(shapeFitter, image, outerCircle, innerRadius, zBounds

fitEllipse()

Short description

Fit an ellipse using the current settings within a search region defined by two concentric circles. For ellipse fitting, least squares methods are very sensitive to noise. Using the ransac method is highly recommended. Image world coordinate system handling: The ellipse is fitted in world coordinates. Missing data handling: Pixels with missing data are ignored, the ellipse is only fitted to valid data.

See also

Image.ShapeFitter.fitCircle

Parameters
Name	Type	Description
shapeFitter	HANDLE	Shape fitter to use.
image	CONST_OBJECT Image	Input image.
outerCircle	CONST_OBJECT Shape	Outer circle of the search region, defining the search region center and outer radius of the search region.
innerRadius	FLOAT	Inner radius of the search region.

Return values
Name	Type	Description
ellipse	OBJECT Shape	Fitted ellipse, or nil on failure.
quality	FLOAT	Vector with fitting quality measurements [meanError, inlierRate, edgePointRate], where meanError is the average fitting error of inlier points in world coordinates, inlierRate is the rate of input points that were used to fit the final ellipse and edgePointRate is the rate of edge probes where an edge point was found. For the least squares method, all points are used and the inlier rate is always 100%.

Sample

ellipse, quality = Image.ShapeFitter.fitEllipse(shapeFitter, image, outerCircle, innerRadius)

fitLine()

Short description

Fit a line using the current settings. The direction parameter specifies the direction of the probe lines, and should be an angle in radians pointing across the edge. - If direction = 0, the probes are oriented left-to-right (expecting to cross the edge when moving left-to-right in the image). - If direction = PI/2, the probes are oriented top-to-bottom (expecting to cross the edge when moving top-to-bottom in the image). Image world coordinate system handling: The line is fitted in world coordinates. Missing data handling: Pixels with missing data are ignored, the line is only fitted to valid data.

See also

Image.ShapeFitter.fitLine3D

Parameters
Name	Type	Description
shapeFitter	HANDLE	Shape fitter to use.
image	CONST_OBJECT Image	Input image.
region	CONST_OBJECT Image.PixelRegion	Input region.
direction	FLOAT	Approximate edge direction in radians, defines the direction of the edge probes.

Return values
Name	Type	Description
lineSeg	OBJECT Shape	Fitted line segment or nil on failure.
quality	FLOAT	Vector with fitting quality measurements [meanError, inlierRate, edgePointRate], where meanError is the average fitting error of inlier points in world coordinates, inlierRate is the rate of input points that were used to fit the final line and edgePointRate is the rate of edge probes where an edge point was found. For the least squares method, all points are used and the inlier rate is always 100%.

Sample

lineSeg, quality = Image.ShapeFitter.fitLine(shapeFitter, image, region, direction)

fitLine3D()

Short description

Fit a 3D line using the current settings. In addition to the xy-region defined by the PixelRegion parameter, the zBounds parameter allows limiting the edge point search space in height. The direction parameter specifies the direction of the probe lines, and should be an angle in radians pointing across the edge. - If direction = 0, the probes are oriented left-to-right (expecting to cross the edge when moving left-to-right in the image). - If direction = PI/2, the probes are oriented top-to-bottom (expecting to cross the edge when moving top-to-bottom in the image). Image world coordinate system handling: The line is fitted in world coordinates. Missing data handling: Pixels with missing data are ignored, the line is only fitted to valid data.

Parameters
Name	Type	Description
shapeFitter	HANDLE	Shape fitter to use.
image	CONST_OBJECT Image	Input image.
region	CONST_OBJECT Image.PixelRegion	Input region, defines an area in xy-space.
zBounds	FLOAT	Two values providing the min and max z values where edges are searched for.
direction	FLOAT	Approximate edge direction in radians, defines the direction of the edge probes.

Return values
Name	Type	Description
lineSegment	OBJECT Shape3D	The fitted line segment or nil on failure.
quality	FLOAT	Vector with fitting quality measurements [meanError, inlierRate, edgePointRate], where meanError is the average fitting error of inlier points in world coordinates, inlierRate is the rate of input points that were used to fit the final line and edgePointRate is the rate of edge probes where an edge point was found. For the least squares method, all points are used and the inlier rate is always 100%.

Sample

lineSegment, quality = Image.ShapeFitter.fitLine3D(shapeFitter, image, region, zBounds, direction)

getEdgePoints()

Short description

Get the edge points used in the last call to any of the 2D fit functions. Intended for visualization, parameter tuning and debugging. Two lists are returned, the first contains all points that were used to fit the final shape. The second list contains all points that were extracted but not used for fitting the shape. For the least squares method, all points are always in the first list. Image world coordinate system handling: The points are returned in world coordinates. Missing data handling: Pixels with missing data are ignored, the edge points are only located on valid data.

Parameters
Name	Type	Description
shapeFitter	HANDLE	Shape fitter to use.

Return values
Name	Type	Description
inlierPoints	OBJECT Point	Points used for the final fitting of the shape, a subset of the detected points.
outlierPoints	OBJECT Point	Points not used for the final fitting, the remainder of the detected points.

Sample

inlierPoints, outlierPoints = Image.ShapeFitter.getEdgePoints(shapeFitter)

getEdgePoints3D()

Short description

Get the 3D edge points used in the last call to any of the 3D fit functions. Intended for visualization, parameter tuning and debugging. Two lists are returned, the first contains all points that were used to fit the final shape. The second list contains all points that were extracted but not used for fitting the shape. For the least squares method, all points are always in the first list. Image world coordinate system handling: The points are returned in world coordinates. Missing data handling: Pixels with missing data are ignored, the edge points are only located on valid data.

Parameters
Name	Type	Description
shapeFitter	HANDLE	Shape fitter to use.

Return values
Name	Type	Description
inlierPoints	OBJECT Point	Points used for the final fitting of the shape, a subset of the detected points.
outlierPoints	OBJECT Point	Points not used for the final fitting, the remainder of the detected points.

Sample

points = Image.ShapeFitter.getEdgePoints3D(shapeFitter)

setDifferenceStep()

Short description

Controls the distance between the two points from which the edge height / strength is measured. Increasing this value can improve the accuracy for very blurred edges, where there is no sharp transition from dark to bright (or from low to high z value for height maps).

See also

Image.ShapeFitter.setThreshold

Parameters
Name	Type	Description
shapeFitter	HANDLE	Shape fitter to use.
step	INT	Difference step in pixels, must be greater than or equal to 1. The default values is 2.

Sample

Image.ShapeFitter.setDifferenceStep(shapeFitter, 5)

setFitMode()

Short description

Set the geometrical fitting mode. The following modes are supported: - LEASTSQUARES uses all points. This is fast and easy, but can produce poor results if there are many spurious edge points nearby (default). When using this method, the inlier rate will always be 100%. - RANSAC is a robust method with outlier rejection. Using this method, spurious edge points can be ignored. This mode requires an outlier margin to be set by setOutlierMargin. The number of iterations can be set by setIterations. - TRIMMED is a two-stage least squares method, where points further away from the fitted shape in the first round than the outlier margin (set by setOutlierMargin) is removed before using least squares again to fit a new shape to the remaining points. This is faster than RANSAC but not as robust to outliers.

Parameters
Name	Type	Description
shapeFitter	HANDLE	Shape fitter to use.
fitMode	ENUM Shape.PointFitMode	Geometrical fitting mode to use. The default is LEASTSQUARES. For many applications this should be changed to RANSAC to be robust to outliers.

Sample

Image.ShapeFitter.setFitMode(shapeFitter, "RANSAC")

setInterpolation()

Short description

Set which interpolation method to use in the edge profiles. The default value, NEAREST, is often a good choice. Changing to LINEAR can give slightly better accuracy, but with additional computational cost.

Parameters
Name	Type	Description
shapeFitter	HANDLE	Shape fitter to use.
interpolation	ENUM InterpolationMethod	Interpolation method.

Sample

Image.ShapeFitter.setInterpolation(shapeFitter, "LINEAR")

setIterations()

Short description

Set the number of iterations in the point fitting step. Only used when setFitMode specifies a robust method like RANSAC. A higher value makes the method more robust, but consumes more computation time. The default is 100 iterations.

See also

Image.ShapeFitter.setFitMode

Parameters
Name	Type	Description
shapeFitter	HANDLE	Shape fitter to use.
iterations	INT	Number of iterations.

Sample

Image.ShapeFitter.setIterations(shapeFitter, 50)

setOutlierMargin()

Short description

Set the outlier margin in world units for the final geometrical fitting step. This parameter is not used for the default fitting method, least squares. The interpretation of the parameter depends on the fitting mode parameter: - ABSOLUTE: the outlier margin is defined in absolute world units (typically mm). Any points further away from the fitted geometrical object than this margin will be ignored. - RANK: the outlier margin is interpreted as a rank measure, defining the rate of points to include. In this case, the margin must be in the range (0.0, 1.0). A rank margin of 0.7 means that only the best fitting 70% of all points will be included, and the rest ignored. In general a larger value means that more points are included in the fitting, which can improve the accuracy as long as all included points are valid. A smaller value makes the algorithm reject more points, which can increases robustness against single erroneous points. The default is an ABSOLUTE margin of 1.0 world units. Image world coordinate system handling: The ABSOLUTE margin is expressed in world coordinate units.

See also

Image.ShapeFitter.setFitMode

Parameters
Name	Type	Description
shapeFitter	HANDLE	Shape fitter to use.
margin	FLOAT	Outlier margin, expressed in world coordinate units or as a rank measure, depending on the marginType.
marginType	ENUM Shape.OutlierMarginType	Outlier margin type. Default is ABSOLUTE.

Sample

Image.ShapeFitter.setOutlierMargin(shapeFitter, margin, marginType)

setPolarity()

Short description

Set the edge polarity that the shape fitter is looking for. This controls the kind of transition that the fitter will look for: - POSITIVE means dark-to-bright for grayscale images, and low-to-high for heightmaps. - NEGATIVE means bright-to-dark for grayscale images and high-to-low for heightmaps. - ANY means any of the above (default). This is related to the probe direction, which for line fitting is a parameter to fitLine. For circle and ellipse fitting, the probe direction is always from the center and out.

Parameters
Name	Type	Description
shapeFitter	HANDLE	Shape fitter to use.
polarity	ENUM Profile.SlopePolarity	Edge polarity.

Sample

Image.ShapeFitter.setPolarity(shapeFitter, "POSITIVE")

setProbeCount()

Short description

Set the edge probe count. A lower number reduces computation time but also reduces accuracy. If a very large number if specified, the number of probes is limited such that the spacing between probes is at most one pixel. Default: 100 probes.

Parameters
Name	Type	Description
shapeFitter	HANDLE	Shape fitter to use.
count	INT	Probe count. Must be >= 4.

Sample

Image.ShapeFitter.setProbeCount(shapeFitter, count)

setSelection()

Short description

Decide which edge point to select if there are several candidates available. The selection is related to the probe direction, which for line fitting is a parameter to fitLine. For circle and ellipse fitting, the probe direction is always from the center and out. If using FIRST or LAST, remember to set the edge threshold. - STRONGEST selects the strongest edge along the probe (default). - FIRST selects the first edge encountered along the probe. - LAST selects the last edge encountered along the probe.

Parameters
Name	Type	Description
shapeFitter	HANDLE	Shape fitter to use.
selection	ENUM EdgeSelection	Edge selection criteria.

Sample

Image.ShapeFitter.setSelection(shapeFitter, "FIRST")

setSide()

Short description

Decide which side of the edge to adjust to. This will adjust the edge points slightly towards the high or low side of the edge, or keep the edge at the center. - CENTER centers the point on the edge (default for intensity images). - HIGH selects the point on the high/bright side of the edge (default for height maps). - LOW selects the point on the low/dark side of the edge.

Parameters
Name	Type	Description
shapeFitter	HANDLE	Shape fitter to use.
side	ENUM Profile.EdgeSide	Edge side.

Sample

Image.ShapeFitter.setSide(shapeFitter, "HIGH")

setThreshold()

Short description

Set the edge threshold. For grayscale images, this can be interpreted as the required edge sharpness. For height maps, this can be interpreted as the edge step. A higher value means that only strong transitions are considered. The default value is 0, which only works well together with STRONGEST as edge selection criterion (see setSelection). If the selection criteria is FIRST or LAST, a threshold should be specified using this function. Image world coordinate system handling: The threshold is expressed in world coordinates, taking the pixel z-size into account.

Parameters
Name	Type	Description
shapeFitter	HANDLE	Shape fitter to use.
threshold	FLOAT	Threshold value. The default value is 0, which only works well together with STRONGEST as edge selection critetion in the setSelection function. Increase threshold for other setting of setSelection.

Sample

Image.ShapeFitter.setThreshold(shapeFitter, 10)

Image.SurfaceFitter

Short description

This is a tool for fitting geometrical 3D object like planes and rectangles to surfaces in range images. To get started, create a SurfaceFitter with the create function and then call fitPlane or fitRectangle to adjust a plane or rectangle to image data. For more detailed control of the fitting behavior, call the set functions before calling the fit function. The surface fitting procedure consists of the following steps: - The set of points corresponding to the pixels within the PixelRegion and z-value bounds is found. A 3D shape enclosing the desired part of the height map can be converted to a PixelRegion and z-bounds via Shape3D.toPixelRegion(). - The geometrical object that best fits the detected points is returned.

Keywords

RANSAC, least squares, model, fitting

Overview

create(), fitPlane(), fitRectangle(), getSurfacePoints(), setFitMode(), setIterations(), setOutlierMargin(), setReductionFactor()

Functions

create()

Short description

Create a surface fitter with default settings.

Return values
Name	Type	Description
surfaceFitter	HANDLE	Created surface fitter.

Sample

surfaceFitter = Image.SurfaceFitter.create()

fitPlane()

Short description

Fit a 3D plane to image height values within a specified region using the current fit mode. The distance along the z-direction from the height map entries to the plane is minimized. Image world coordinate system handling: The plane is fitted in world coordinates. Missing data handling: Pixels with missing data are disregarded, the plane is only fitted to valid data.

Parameters
Name	Type	Description
surfaceFitter	HANDLE	Surface fitter to use.
image	CONST_OBJECT Image	Input image.
region	CONST_OBJECT Image.PixelRegion	Input region indicating which area to fit to. Optional, the default is to use the entire image.
boundsZ	FLOAT	Lower and upper z-bound. Optional, the default is to use all points.

Return values
Name	Type	Description
plane	OBJECT Shape3D	The fitted plane.
quality	FLOAT	Vector with fitting quality measurements [meanError, inlierRate], where meanError is the average fitting error of inlier points in world coordinates and inlierRate is the rate of input points that were accepted as belonging to the plane.

Sample

plane, quality = Image.SurfaceFitter.fitPlane(surfaceFitter, image, region, lowerBoundZ, upperBoundZ)

fitRectangle()

Short description

Fit a rectangle in 3D to image height values within a specified region using the current fit mode. Similar to fitPlane but the rectangle is limited to the extent of the fitted points. By default, the rectangle is rotated in-plane to find the minimal area rectangle enclosing the inlier points. The distance along the z-direction from the height map entries to the plane is minimized. Image world coordinate system handling: The rectangle is fitted in world coordinates. Missing data handling: Pixels with missing data are disregarded, the rectangle is only fitted to valid data.

Parameters
Name	Type	Description
surfaceFitter	HANDLE	Surface fitter to use.
image	CONST_OBJECT Image	Input image.
region	CONST_OBJECT Image.PixelRegion	Input region indicating which area to fit to. Optional, the default is to use the entire image.
boundsZ	FLOAT	Lower and upper z-bound. Optional, the default is to use all points.
oriented	BOOL	Flag controlling if the rectangle should be rotated to minimize rectangle area (default). If set to false, the in-plane rotation of the fitted rectangle is related to the coordinate axes.

Return values
Name	Type	Description
rectangle	OBJECT Shape3D	The fitted rectangle.
quality	FLOAT	Vector with fitting quality measurements [meanError, inlierRate], where meanError is the average fitting error of inlier points in world coordinates and inlierRate is the rate of input points that were accepted as belonging to the rectangle.

Sample

rectangle, quality = Image.SurfaceFitter.fitRectangle(surfaceFitter, image, region, zBounds, oriented)

getSurfacePoints()

Short description

Get the 3D points used in the last call to any of the fit functions. Intended for visualization, parameter tuning and debugging. Two lists are returned, the first contains all points that were used to fit the final shape. The second list contains all points that were extracted but not used for fitting the shape. For the least squares method, all points are always in the first list. The number of returned points is limited. If the total number of points exceeds the set limit, the last points are skipped. Image world coordinate system handling: The returned points are in world coordinates. Missing data handling: Pixels with missing data are disregarded.

Parameters
Name	Type	Description
surfaceFitter	HANDLE	Surface fitter to use.
pointCountLimit	INT	Limit the number of points returned. Optional, default is 50000 points maximum.

Return values
Name	Type	Description
inlierPoints	OBJECT Point	Points used for the final fitting of the shape, a subset of the detected points.
outlierPoints	OBJECT Point	Points not used for the final fitting, the remainder of the detected points.

Sample

inlierPoints, outlierPoints = Image.SurfaceFitter.getSurfacePoints(surfaceFitter)

setFitMode()

Short description

Set the geometrical fitting mode. The following modes are supported: - LEASTSQUARES includes all points. This is fast and easy, but can produce poor results if there are many spurious points nearby (default). - RANSAC is a robust method with outlier rejection. Using this method, spurious points can be ignored. This mode requires an outlier margin to be set by setOutlierMargin and uses the number of iterations set through setIterations. - TRIMMED is faster than ransac and more robust than least squares. It first fits a plane to all points using least squares. The points farther from the plane than set outlierMargin are removed and a new plane is fitted to the remaining points using least squares.

Parameters
Name	Type	Description
surfaceFitter	HANDLE	Surface fitter to use.
fitMode	ENUM Shape.PointFitMode	Geometrical fitting mode to use. The default is LEASTSQUARES. For many applications this should be changed to RANSAC to be robust to outliers.

Sample

Image.SurfaceFitter.setFitMode(surfaceFitter, fitMode)

setIterations()

Short description

See also

Image.SurfaceFitter.setFitMode

Parameters
Name	Type	Description
surfaceFitter	HANDLE	Surface fitter to use.
iterations	INT	Number of iterations. The default is 100 iterations.

Sample

Image.SurfaceFitter.setIterations(surfaceFitter, iterations)

setOutlierMargin()

Short description

Set the outlier margin for the final geometrical fitting step. The interpretation of the margin value depends on the margin type. For an ABSOLUTE margin, any points further away from the fitted geometrical object than this margin will be ignored. The RANK margin includes a given part of the point set, i.e. a rank margin of 0.7 will search for the best shape fitting 70% of the points. For both margin types, a large value means that more points are included in the fitting, which can improve the accuracy as long as all included points are valid. A smaller value makes the algorithm reject more points, which can increases robustness against single erroneous points. The default value is 1.0 world units. Image world coordinate system handling: The ABSOLUTE margin is in image world coordinates.

See also

Image.SurfaceFitter.setFitMode

Parameters
Name	Type	Description
surfaceFitter	HANDLE	Surface fitter to use.
margin	FLOAT	Outlier margin, expressed in world coordinate unit or as a rank measure, depending on the marginType.
marginType	ENUM Shape.OutlierMarginType	Outlier margin type. Default is ABSOLUTE.

Sample

Image.SurfaceFitter.setOutlierMargin(surfaceFitter, margin, marginType)

setReductionFactor()

Short description

Allows for quick reduction of the number of points to fit a shape to for large surfaces. Every N:th pixel in every N:th row is used, reducing computation time. Setting this parameter to one (default) fits the shape to all pixels in the region. Setting this parameter to two, approximately one quarter of the pixels are used.

Parameters
Name	Type	Description
surfaceFitter	HANDLE	Surface fitter to use.
n	INT	Using every n:th pixel in every n:th row.

Sample

Image.SurfaceFitter.setReductionFactor(surfaceFitter, n)

LED

Short description

Access to the LEDs of the device to change their mode. Can be used to activate or deactivate LEDs. If LED support for colors might be possible, there is the function setColor which can be used to change the LED color.

Overview

activate(), blink(), create(), deactivate(), setColor()

Functions

activate()

Short description

Sets the LED to active. Some LEDs might deactivate theirself after a max. possible active time (e.g. 10 secs). This depends on the concrete LED.

Parameters
Name	Type	Description
handle	HANDLE	Unique handle to the LED
activeTimeMs	INT	The time the LED is active. Per default stays active forever or might be deactivated after the max. possible active time of the LED (see concrete LED documentation)

Sample

LED.activate(handle)

blink()

Short description

Sets the LED to blinking mode so that it is automatically set to active and inactive for the specified times.

Parameters
Name	Type	Description
handle	HANDLE	Unique handle of the LED
pulsTimeMs	INT	The time the LED is active
pauseTimeMs	INT	The time the LED is inactive. If not specified, the pulseTimeMs is also used as pauseTimeMs.

Sample

LED.blink(handle, 600, 300)

create()

Short description

Creates a handle for the LED if exists and not already in use.

Parameters
Name	Type	Description
ledName	ENUM LEDs	The name of the LED to use

Return values
Name	Type	Description
handle	HANDLE	Unique handle for the LED. Nil if not available or already in use.

Sample

handle = LED.create("LED_1")

deactivate()

Short description

Sets the LED to inactive.

Parameters
Name	Type	Description
handle	HANDLE	Unique handle to the LED

Sample

LED.deactivate(handle)

setColor()

Short description

If the LED supports multiple colors it could be set here. If LED is already activated, the color is switched directly. Default is set all to full color (white or the only color the LED supports). The possible colors of the LED could be get known from the device manual.

Parameters
Name	Type	Description
handle	HANDLE	Unique handle of the LED
color	AUTO	Flexible parameter to set the color. Could be a name of a color, a single int RGB value (e.g. 0x123456) or a vector of three ints for each part of the RGB value.

Sample

by name: LED.setColor(handle, "red")
by RGB value: LED.setColor(handle, {255,0,0} )
by RGB state: LED.setColor(handle, {true,false,false} )

LUA.debug

Short description

This library provides the functionality of the debug interface (4.9) to Lua programs. You should exert care when using this library. Several of its functions violate basic assumptions about Lua code (e.g., that variables local to a function cannot be accessed from outside; that userdata metatables cannot be changed by Lua code; that Lua programs do not crash) and therefore can compromise otherwise secure code. Moreover, some functions in this library may be slow. All functions in this library are provided inside the debug table. All functions that operate over a thread have an optional first argument which is the thread to operate over. The default is always the current thread.

Overview

getinfo(), getlocal(), getmetatable(), getregistry(), traceback()

Functions

getinfo()

Short description

Returns a table with information about a function. You can give the function directly or you can give a number as the value of f, which means the function running at level f of the call stack of the given thread: level 0 is the current function (getinfo itself); level 1 is the function that called getinfo (except for tail calls, which do not count on the stack); and so on. If f is a number larger than the number of active functions, then getinfo returns nil. The returned table can contain all the fields returned by lua_getinfo, with the string what describing which fields to fill in. The default for what is to get all information available, except the table of valid lines. If present, the option 'f' adds a field named func with the function itself. If present, the option 'L' adds a field named activelines with the table of valid lines. For instance, the expression debug.getinfo(1,"n").name returns a name for the current function, if a reasonable name can be found, and the expression debug.getinfo(print) returns a table with all available information about the print function.

Parameters
Name	Type	Description
thread	AUTO	thread
f	AUTO
what	STRING

Return values
Name	Type	Description
table	AUTO	table

getlocal()

Short description

This function returns the name and the value of the local variable with index local of the function at level f of the stack. This function accesses not only explicit local variables, but also parameters, temporaries, etc. The first parameter or local variable has index 1, and so on, following the order that they are declared in the code, counting only the variables that are active in the current scope of the function. Negative indices refer to vararg parameters; -1 is the first vararg parameter. The function returns nil if there is no variable with the given index, and raises an error when called with a level out of range. (You can call debug.getinfo to check whether the level is valid.) Variable names starting with '(' (open parenthesis) represent variables with no known names (internal variables such as loop control variables, and variables from chunks saved without debug information). The parameter f may also be a function. In that case, getlocal returns only the name of function parameters.

Parameters
Name	Type	Description
thread	AUTO	thread
f	AUTO
local	INT

Return values
Name	Type	Description
name	STRING
value	AUTO

getmetatable()

Short description

Returns the metatable of the given value or nil if it does not have a metatable.

Parameters
Name	Type	Description
value	AUTO

Return values
Name	Type	Description
table	AUTO	table

getregistry()

Short description

Returns the registry table (see lua reference 4.5).

Return values
Name	Type	Description
table	AUTO	table

traceback()

Short description

If message is present but is neither a string nor nil, this function returns message without further processing. Otherwise, it returns a string with a traceback of the call stack. The optional message string is appended at the beginning of the traceback. An optional level number tells at which level to start the traceback (default is 1, the function calling traceback).

Parameters
Name	Type	Description
thread	AUTO	thread
message	STRING
level	INT

Return values
Name	Type	Description
message	STRING

LUA.math

Short description

This library provides basic mathematical functions. It provides all its functions and constants inside the table math. Functions with the annotation "integer/float" give integer results for integer arguments and float results for float (or mixed) arguments. Rounding functions (math.ceil, math.floor, and math.modf) return an integer when the result fits in the range of an integer, or a float otherwise.

Overview

abs(), acos(), asin(), atan(), atan2(), ceil(), cos(), cosh(), deg(), exp(), floor(), fmod(), frexp(), ldexp(), log(), log10(), max(), min(), modf(), pow(), rad(), random(), randomseed(), sin(), sinh(), sqrt(), tan(), tanh(), tointeger(), type(), ult()

Functions

abs()

Short description

Returns the absolute value of x. (integer/float)

Parameters
Name	Type	Description
x	FLOAT	number

Return values
Name	Type	Description
abs	FLOAT	number

acos()

Short description

Returns the arc cosine of x (in radians).

Parameters
Name	Type	Description
x	FLOAT	number

Return values
Name	Type	Description
acos	FLOAT	number

asin()

Short description

Returns the arc sine of x (in radians).

Parameters
Name	Type	Description
x	FLOAT	number

Return values
Name	Type	Description
asin	FLOAT	number

atan()

Short description

Returns the arc tangent of y/x (in radians), but uses the signs of both parameters to find the quadrant of the result. (It also handles correctly the case of x being zero.) The default value for x is 1, so that the call math.atan(y) returns the arc tangent of y.

Parameters
Name	Type	Description
x	FLOAT	number

Return values
Name	Type	Description
atan	FLOAT	number

atan2()

Short description

DEPRECATED: Use "atan" instead with additional argument. Returns the arc tangent of y/x (in radians), but uses the signs of both parameters to find the quadrant of the result. (It also handles correctly the case of x being zero.)

Parameters
Name	Type	Description
y	FLOAT	number
x	FLOAT	number

Return values
Name	Type	Description
atan2	FLOAT	number

ceil()

Short description

Returns the smallest integral value larger than or equal to x.

Parameters
Name	Type	Description
x	FLOAT	number

Return values
Name	Type	Description
ceil	FLOAT	number

cos()

Short description

Returns the cosine of x (assumed to be in radians).

Parameters
Name	Type	Description
x	FLOAT	number

Return values
Name	Type	Description
cos	FLOAT	number

cosh()

Short description

DEPRECATED: Use an external library or implement it in Lua. Returns the hyperbolic cosine of x.

Parameters
Name	Type	Description
x	FLOAT	number

Return values
Name	Type	Description
cosh	FLOAT	number

deg()

Short description

Returns the angle x (given in radians) in degrees.

Parameters
Name	Type	Description
x	FLOAT	number

Return values
Name	Type	Description
deg	FLOAT	number

exp()

Short description

Returns the value e^x (where e is the base of natural logarithms).

Parameters
Name	Type	Description
x	FLOAT	number

Return values
Name	Type	Description
exp	FLOAT	number

floor()

Short description

Returns the largest integral value smaller than or equal to x.

Parameters
Name	Type	Description
x	FLOAT	number

Return values
Name	Type	Description
floor	FLOAT	number

fmod()

Short description

Returns the remainder of the division of x by y that rounds the quotient towards zero. (integer/float)

Parameters
Name	Type	Description
x	FLOAT	number
y	FLOAT	number

Return values
Name	Type	Description
fmod	FLOAT	number

frexp()

Short description

DEPRECATED: Use an external library or implement it in Lua. Returns m and e such that x = m2^e, e is an integer and the absolute value of m is in the range [0.5, 1) (or zero when x is zero).

Parameters
Name	Type	Description
x	FLOAT	number

Return values
Name	Type	Description
m	FLOAT	number
e	FLOAT	number

ldexp()

Short description

DEPRECATED: Replace with "x*2.0^e". Returns m2^e (e should be an integer).

Parameters
Name	Type	Description
m	FLOAT	number
e	FLOAT	number

Return values
Name	Type	Description
ldexp	FLOAT	number

log()

Short description

Returns the logarithm of x in the given base. The default for base is e (so that the function returns the natural logarithm of x).

Parameters
Name	Type	Description
x	FLOAT	number
base	FLOAT	number

Return values
Name	Type	Description
log	FLOAT	number

log10()

Short description

DEPRECATED: Use "log" instead with additional argument. Returns the logarithm of x in base 10.

Parameters
Name	Type	Description
x	FLOAT	number

Return values
Name	Type	Description
log10	FLOAT	number

max()

Short description

Returns the argument with the maximum value, according to the Lua operator < (integer/float)

Parameters
Name	Type	Description
x1	FLOAT	number
x2	FLOAT	number
xN	FLOAT	number

Return values
Name	Type	Description
max	FLOAT	number

min()

Short description

Returns the argument with the minimum value, according to the Lua operator >. (integer/float)

Parameters
Name	Type	Description
x1	FLOAT	number
x2	FLOAT	number
xN	FLOAT	number

Return values
Name	Type	Description
min	FLOAT	number

modf()

Short description

Returns the integral part of x and the fractional part of x. Its second result is always a float.

Parameters
Name	Type	Description
x	FLOAT	number

Return values
Name	Type	Description
integral	FLOAT	number
fractional	FLOAT	number

pow()

Short description

DEPRECATED: Replace with "x^y". Returns x^y. (You can also use the expression x^y to compute this value.)

Parameters
Name	Type	Description
x	FLOAT	number
y	FLOAT	number

Return values
Name	Type	Description
pow	FLOAT	number

rad()

Short description

Returns the angle x (given in degrees) in radians.

Parameters
Name	Type	Description
x	FLOAT	number

Return values
Name	Type	Description
rad	FLOAT	number

random()

Short description

When called without arguments, returns a pseudo-random float with uniform distribution in the range [0,1). When called with two integers m and n, math.random returns a pseudo-random integer with uniform distribution in the range [m, n]. (The value n-m cannot be negative and must fit in a Lua integer.) The call math.random(n) is equivalent to math.random(1,n). This function is an interface to the underling pseudo-random generator function provided by C.

Parameters
Name	Type	Description
m	FLOAT	number
n	FLOAT	number

Return values
Name	Type	Description
random	FLOAT	number

randomseed()

Short description

Sets x as the "seed" for the pseudo-random generator: equal seeds produce equal sequences of numbers.

Parameters
Name	Type	Description
x	FLOAT	number

sin()

Short description

Returns the sine of x (assumed to be in radians).

Parameters
Name	Type	Description
x	FLOAT	number

Return values
Name	Type	Description
sin	FLOAT	number

sinh()

Short description

DEPRECATED: Use an external library or implement it in Lua. Returns the hyperbolic sine of x.

Parameters
Name	Type	Description
x	FLOAT	number

Return values
Name	Type	Description
sinh	FLOAT	number

sqrt()

Short description

Returns the square root of x. (You can also use the expression x^0.5 to compute this value.)

Parameters
Name	Type	Description
x	FLOAT	number

Return values
Name	Type	Description
sqrt	FLOAT	number

tan()

Short description

Returns the tangent of x (assumed to be in radians).

Parameters
Name	Type	Description
x	FLOAT	number

Return values
Name	Type	Description
tan	FLOAT	number

tanh()

Short description

DEPRECATED: Use an external library or implement it in Lua. Returns the hyperbolic tangent of x.

Parameters
Name	Type	Description
x	FLOAT	number

Return values
Name	Type	Description
tanh	FLOAT	number

tointeger()

Short description

If the value x is convertible to an integer, returns that integer. Otherwise, returns nil.

Parameters
Name	Type	Description
x	FLOAT	number

Return values
Name	Type	Description
integer	INT

type()

Short description

Returns "integer" if x is an integer, "float" if it is a float, or nil if x is not a number.

Parameters
Name	Type	Description
x	FLOAT	number

Return values
Name	Type	Description
type	STRING

ult()

Short description

Returns a boolean, true if integer m is below integer n when they are compared as unsigned integers.

Parameters
Name	Type	Description
m	INT
n	INT

Return values
Name	Type	Description
ult	BOOL

LUA.string

Short description

This library provides generic functions for string manipulation, such as finding and extracting substrings, and pattern matching. When indexing a string in Lua, the first character is at position 1 (not at 0, as in C). Indices are allowed to be negative and are interpreted as indexing backwards, from the end of the string. Thus, the last character is at position -1, and so on. The string library provides all its functions inside the table string. It also sets a metatable for strings where the __index field points to the string table. Therefore, you can use the string functions in object-oriented style. For instance, string.byte(s,i) can be written as s:byte(i). The string library assumes one-byte character encodings. 6.4.1 - Patterns Patterns in Lua are described by regular strings, which are interpreted as patterns by the pattern-matching functions string.find, string.gmatch, string.gsub, and string.match. This section describes the syntax and the meaning (that is, what they match) of these strings. Character Class: A character class is used to represent a set of characters. The following combinations are allowed in describing a character class: x: (where x is not one of the magic characters ^$()%.[]-?) represents the character x itself. .: (a dot) represents all characters. %a: represents all letters. %c: represents all control characters. %d: represents all digits. %g: represents all printable characters except space. %l: represents all lowercase letters. %p: represents all punctuation characters. %s: represents all space characters. %u: represents all uppercase letters. %w: represents all alphanumeric characters. %x: represents all hexadecimal digits. %x: (where x is any non-alphanumeric character) represents the character x. This is the standard way to escape the magic characters. Any non-alphanumeric character (including all punctuation characters, even the non-magical) can be preceded by a '%' when used to represent itself in a pattern. [set]: represents the class which is the union of all characters in set. A range of characters can be specified by separating the end characters of the range, in ascending order, with a '-'. All classes %x described above can also be used as components in set. All other characters in set represent themselves. For example, [%w_] (or [_%w]) represents all alphanumeric characters plus the underscore, [0-7] represents the octal digits, and [0-7%l%-] represents the octal digits plus the lowercase letters plus the '-' character. The interaction between ranges and classes is not defined. Therefore, patterns like [%a-z] or [a-%%] have no meaning. [^set]: represents the complement of set, where set is interpreted as above. For all classes represented by single letters (%a, %c, etc.), the corresponding uppercase letter represents the complement of the class. For instance, %S represents all non-space characters. The definitions of letter, space, and other character groups depend on the current locale. In particular, the class [a-z] may not be equivalent to %l. Pattern Item: A pattern item can be a single character class, which matches any single character in the class; a single character class followed by '*', which matches zero or more repetitions of characters in the class. These repetition items will always match the longest possible sequence; a single character class followed by '', which matches one or more repetitions of characters in the class. These repetition items will always match the longest possible sequence; a single character class followed by '-', which also matches zero or more repetitions of characters in the class. Unlike '', these repetition items will always match the shortest possible sequence; a single character class followed by '?', which matches zero or one occurrence of a character in the class. It always matches one occurrence if possible; %n, for n between 1 and 9; such item matches a substring equal to the n-th captured string (see below); %bxy, where x and y are two distinct characters; such item matches strings that start with x, end with y, and where the x and y are balanced. This means that, if one reads the string from left to right, counting +1 for an x and -1 for a y, the ending y is the first y where the count reaches 0. For instance, the item %b() matches expressions with balanced parentheses. %f[set], a frontier pattern; such item matches an empty string at any position such that the next character belongs to set and the previous character does not belong to set. The set set is interpreted as previously described. The beginning and the end of the subject are handled as if they were the character '\0'. Pattern: A pattern is a sequence of pattern items. A caret '^' at the beginning of a pattern anchors the match at the beginning of the subject string. A '$' at the end of a pattern anchors the match at the end of the subject string. At other positions, '^' and '$' have no special meaning and represent themselves. Captures: A pattern can contain sub-patterns enclosed in parentheses; they describe captures. When a match succeeds, the substrings of the subject string that match captures are stored (captured) for future use. Captures are numbered according to their left parentheses. For instance, in the pattern "(a*(.)%w(%s*))", the part of the string matching "a*(.)%w(%s*)" is stored as the first capture (and therefore has number 1); the character matching "." is captured with number 2, and the part matching "%s*" has number 3. As a special case, the empty capture () captures the current string position (a number). For instance, if we apply the pattern "()aa()" on the string "flaaap", there will be two captures: 3 and 5. 6.4.2 - Format Strings for Pack and Unpack The first argument to string.pack, string.packsize, and string.unpack is a format string, which describes the layout of the structure being created or read. A format string is a sequence of conversion options. The conversion options are as follows: <: sets little endian >: sets big endian =: sets native endian ![n]: sets maximum alignment to n (default is native alignment) b: a signed byte (char) B: an unsigned byte (char) h: a signed short (native size) H: an unsigned short (native size) l: a signed long (native size) L: an unsigned long (native size) j: a lua_Integer J: a lua_Unsigned T: a size_t (native size) i[n]: a signed int with n bytes (default is native size) I[n]: an unsigned int with n bytes (default is native size) f: a float (native size) d: a double (native size) n: a lua_Number cn: a fixed-sized string with n bytes z: a zero-terminated string s[n]: a string preceded by its length coded as an unsigned integer with n bytes (default is a size_t) x: one byte of padding Xop: an empty item that aligns according to option op (which is otherwise ignored) ' ': (empty space) ignored (A "[n]" means an optional integral numeral.) Except for padding, spaces, and configurations (options "xX <⇒!"), each option corresponds to an argument (in string.pack) or a result (in string.unpack). For options "!n", "sn", "in", and "In", n can be any integer between 1 and 16. All integral options check overflows; string.pack checks whether the given value fits in the given size; string.unpack checks whether the read value fits in a Lua integer. Any format string starts as if prefixed by "!1=", that is, with maximum alignment of 1 (no alignment) and native endianness. Alignment works as follows: For each option, the format gets extra padding until the data starts at an offset that is a multiple of the minimum between the option size and the maximum alignment; this minimum must be a power of 2. Options "c" and "z" are not aligned; option "s" follows the alignment of its starting integer. All padding is filled with zeros by string.pack (and ignored by string.unpack).

Overview

byte(), char(), dump(), find(), format(), gmatch(), gsub(), len(), lower(), match(), pack(), packsize(), rep(), reverse(), sub(), unpack(), upper()

Functions

byte()

Short description

Returns the internal numeric codes of the characters s[i], s[i+1], …, s[j]. The default value for i is 1; the default value for j is i. These indices are corrected following the same rules of function string.sub. Numeric codes are not necessarily portable across platforms.

Parameters
Name	Type	Description
s	STRING
i	INT
j	INT

Return values
Name	Type	Description
byte	INT

char()

Short description

Receives zero or more integers. Returns a string with length equal to the number of arguments, in which each character has the internal numeric code equal to its corresponding argument. Numeric codes are not necessarily portable across platforms.

Parameters
Name	Type	Description
x1	INT
xN	INT

Return values
Name	Type	Description
string	STRING

dump()

Short description

Returns a string containing a binary representation (a binary chunk) of the given function, so that a later load on this string returns a copy of the function (but with new upvalues). If strip is a true value, the binary representation may not include all debug information about the function, to save space. Functions with upvalues have only their number of upvalues saved. When (re)loaded, those upvalues receive fresh instances containing nil. (You can use the debug library to serialize and reload the upvalues of a function in a way adequate to your needs.)

Parameters
Name	Type	Description
function	AUTO	function

Return values
Name	Type	Description
binary	BINARY

find()

Short description

Looks for the first match of pattern (see 6.4.1) in the string s. If it finds a match, then find returns the indices of s where this occurrence starts and ends; otherwise, it returns nil. A third, optional numeric argument init specifies where to start the search; its default value is 1 and can be negative. A value of true as a fourth, optional argument plain turns off the pattern matching facilities, so the function does a plain "find substring" operation, with no characters in pattern being considered magic. Note that if plain is given, then init must be given as well. If the pattern has captures, then in a successful match the captured values are also returned, after the two indices.

Parameters
Name	Type	Description
s	STRING
pattern	STRING
init	INT
plain	BOOL

Return values
Name	Type	Description
x1	STRING
xN	STRING

format()

Short description

Returns a formatted version of its variable number of arguments following the description given in its first argument (which must be a string). The format string follows the same rules as the ISO C function sprintf. The only differences are that the options/modifiers *, h, L, l, n, and p are not supported and that there is an extra option, q. The q option formats a string between double quotes, using escape sequences when necessary to ensure that it can safely be read back by the Lua interpreter. For instance, the call string.format('%q', 'a string with "quotes" and \n new line') may produce the string: "a string with \"quotes\" and \ new line" Options A, a, E, e, f, G, and g all expect a number as argument. Options c, d, i, o, u, X, and x expect an integer. Option q expects a string. Option s expects a string; if its argument is not a string, it is converted to one following the same rules of tostring. If the option has any modifier (flags, width, length), the string argument should not contain embedded zeros. When Lua is compiled with a non-C99 compiler, options A and a (hexadecimal floats) do not support any modifier (flags, width, length).

Parameters
Name	Type	Description
formatstring	STRING
x1	AUTO
xN	AUTO

gmatch()

Short description

Returns an iterator function that, each time it is called, returns the next captures from pattern (see 6.4.1) over the string s. If pattern specifies no captures, then the whole match is produced in each call. As an example, the following loop will iterate over all the words from string s, printing one per line: s = "hello world from Lua" for w in string.gmatch(s, "%a+") do print(w) end The next example collects all pairs key=value from the given string into a table: t = {} s = "from=world, to=Lua" for k, v in string.gmatch(s, "(%w+)=(%w+)") do t[k] = v end For this function, a caret '^' at the start of a pattern does not work as an anchor, as this would prevent the iteration.

Parameters
Name	Type	Description
s	STRING
pattern	STRING

Return values
Name	Type	Description
function	AUTO	function

gsub()

Short description

Returns a copy of s in which all (or the first n, if given) occurrences of the pattern (see 6.4.1) have been replaced by a replacement string specified by repl, which can be a string, a table, or a function. gsub also returns, as its second value, the total number of matches that occurred. The name gsub comes from Global SUBstitution. If repl is a string, then its value is used for replacement. The character % works as an escape character: any sequence in repl of the form %d, with d between 1 and 9, stands for the value of the d-th captured substring. The sequence %0 stands for the whole match. The sequence %% stands for a single %. If repl is a table, then the table is queried for every match, using the first capture as the key. If repl is a function, then this function is called every time a match occurs, with all captured substrings passed as arguments, in order. In any case, if the pattern specifies no captures, then it behaves as if the whole pattern was inside a capture. If the value returned by the table query or by the function call is a string or a number, then it is used as the replacement string; otherwise, if it is false or nil, then there is no replacement (that is, the original match is kept in the string). Here are some examples: x = string.gsub("hello world", "(%w+)", "%1 %1") -→ x="hello hello world world" x = string.gsub("hello world", "%w+", "%0 %0", 1) -→ x="hello hello world" x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") -→ x="world hello Lua from" x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) -→ x="home = /home/roberto, user = roberto" x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) return load(s)() end) -→ x="4+5 = 9" local t = {name="lua", version="5.3"} x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) -→ x="lua-5.3.tar.gz"

Parameters
Name	Type	Description
s	STRING
pattern	STRING
repl	AUTO
n	AUTO	number

Return values
Name	Type	Description
copyS	STRING
numberOfMatches	INT

len()

Short description

Receives a string and returns its length. The empty string "" has length 0. Embedded zeros are counted, so "a\000bc\000" has length 5.

Parameters
Name	Type	Description
s	STRING

Return values
Name	Type	Description
len	INT

lower()

Short description

Receives a string and returns a copy of this string with all uppercase letters changed to lowercase. All other characters are left unchanged. The definition of what an uppercase letter is depends on the current locale.

Parameters
Name	Type	Description
s	STRING

Return values
Name	Type	Description
string	STRING

match()

Short description

Looks for the first match of pattern in the string s. If it finds one, then match returns the captures from the pattern; otherwise it returns nil. If pattern specifies no captures, then the whole match is returned. A third, optional numerical argument init specifies where to start the search; its default value is 1 and can be negative.

Parameters
Name	Type	Description
s	STRING
pattern	STRING
init	INT

Return values
Name	Type	Description
string	STRING

pack()

Short description

Returns a binary string containing the values v1, v2, etc. packed (that is, serialized in binary form) according to the format string fmt (see string description).

Parameters
Name	Type	Description
fmt	STRING
v1	AUTO
vN	AUTO

Return values
Name	Type	Description
binaryString	STRING

packsize()

Short description

Returns the size of a string resulting from string.pack with the given format. The format string cannot have the variable-length options 's' or 'z' (see 6.4.2).

Parameters
Name	Type	Description
fmt	STRING

Return values
Name	Type	Description
packsize	INT

rep()

Short description

Returns a string that is the concatenation of n copies of the string s separated by the string sep. The default value for sep is the empty string (that is, no separator). Returns the empty string if n is not positive. (Note that it is very easy to exhaust the memory of your machine with a single call to this function.)

Parameters
Name	Type	Description
s	STRING
n	INT
sep	STRING

Return values
Name	Type	Description
string	STRING

reverse()

Short description

Returns a string that is the string s reversed.

Parameters
Name	Type	Description
s	STRING

Return values
Name	Type	Description
string	STRING

sub()

Short description

Returns the substring of s that starts at i and continues until j; i and j can be negative. If j is absent, then it is assumed to be equal to -1 (which is the same as the string length). In particular, the call string.sub(s,1,j) returns a prefix of s with length j, and string.sub(s, -i) returns a suffix of s with length i. If, after the translation of negative indices, i is less than 1, it is corrected to 1. If j is greater than the string length, it is corrected to that length. If, after these corrections, i is greater than j, the function returns the empty string.

Parameters
Name	Type	Description
s	STRING
i	INT
j	INT

Return values
Name	Type	Description
substring	STRING

unpack()

Short description

Returns the values packed in string s (see string.pack) according to the format string fmt (see 6.4.2). An optional pos marks where to start reading in s (default is 1). After the read values, this function also returns the index of the first unread byte in s.

Parameters
Name	Type	Description
fmt	STRING
s	STRING
pos	INT
v1	AUTO
v2	AUTO
vN	AUTO
firstUnreadByte	INT

upper()

Short description

Receives a string and returns a copy of this string with all lowercase letters changed to uppercase. All other characters are left unchanged. The definition of what a lowercase letter is depends on the current locale.

Parameters
Name	Type	Description
s	STRING

Return values
Name	Type	Description
string	STRING

LUA.table

Short description

This library provides generic functions for table manipulation. It provides all its functions inside the table table. Remember that, whenever an operation needs the length of a table, the table must be a proper sequence or have a __len metamethod (see 3.4.7). All functions ignore non-numeric keys in the tables given as arguments.

Overview

concat(), insert(), move(), pack(), remove(), sort(), unpack()

Functions

concat()

Short description

Given a list where all elements are strings or numbers, returns the string list[i]..sep..list[i+1] … sep..list[j]. The default value for sep is the empty string, the default for i is 1, and the default for j is ##list. If i is greater than j, returns the empty string.

Parameters
Name	Type	Description
list	AUTO	table
sep	STRING
i	INT
j	INT

Return values
Name	Type	Description
concat	STRING

insert()

Short description

Inserts element value at position pos in list, shifting up the elements list[pos], list[pos+1], …, list[list]. The default value for pos is list+1, so that a call table.insert(t,x) inserts x at the end of list t.

Parameters
Name	Type	Description
list	AUTO	table
pos	INT
value	AUTO

move()

Short description

Moves elements from table a1 to table a2. This function performs the equivalent to the following multiple assignment: a2[t],… = a1[f],…,a1[e]. The default for a2 is a1. The destination range can overlap with the source range. The number of elements to be moved must fit in a Lua integer.

Parameters
Name	Type	Description
a1	AUTO	table
f	INT
e	INT
t	INT
a2	AUTO	table

pack()

Short description

Returns a new table with all parameters stored into keys 1, 2, etc. and with a field "n" with the total number of parameters. Note that the resulting table may not be a sequence.

Parameters
Name	Type	Description
x1	AUTO
xN	AUTO

Return values
Name	Type	Description
table	AUTO	table

remove()

Short description

Removes from list the element at position pos, returning the value of the removed element. When pos is an integer between 1 and list, it shifts down the elements list[pos+1], list[pos+2], …, list[list] and erases element list[list]; The index pos can also be 0 when list is 0, or list + 1; in those cases, the function erases the element list[pos]. The default value for pos is list, so that a call table.remove(l) removes the last element of list l.

Parameters
Name	Type	Description
list	AUTO	table
pos	INT

sort()

Short description

Sorts list elements in a given order, in-place, from list[1] to list[##list]. If comp is given, then it must be a function that receives two list elements and returns true when the first element must come before the second in the final order (so that, after the sort, i < j implies not comp(list[j],list[i])). If comp is not given, then the standard Lua operator > is used instead. Note that the comp function must define a strict partial order over the elements in the list; that is, it must be asymmetric and transitive. Otherwise, no valid sort may be possible. The sort algorithm is not stable; that is, elements not comparable by the given order (e.g., equal elements) may have their relative positions changed by the sort.

Parameters
Name	Type	Description
list	AUTO	table
comp	AUTO	function

unpack()

Short description

Returns the elements from the given list. This function is equivalent to return list[i], list[i+1], …, list[j] By default, i is 1 and j is ##list.

Parameters
Name	Type	Description
list	AUTO	table

Return values
Name	Type	Description
x1	AUTO
xN	AUTO

LUA.utf8

Short description

This library provides basic support for UTF-8 encoding. It provides all its functions inside the table utf8. This library does not provide any support for Unicode other than the handling of the encoding. Any operation that needs the meaning of a character, such as character classification, is outside its scope. Unless stated otherwise, all functions that expect a byte position as a parameter assume that the given position is either the start of a byte sequence or one plus the length of the subject string. As in the string library, negative indices count from the end of the string.

Overview

char(), codepoint(), codes(), len(), offset()

Functions

char()

Short description

Receives zero or more integers, converts each one to its corresponding UTF-8 byte sequence and returns a string with the concatenation of all these sequences.

Parameters
Name	Type	Description
x1	INT
xN	INT

Return values
Name	Type	Description
string	STRING

codepoint()

Short description

Returns the codepoints (as integers) from all characters in s that start between byte position i and j (both included). The default for i is 1 and for j is i. It raises an error if it meets any invalid byte sequence.

Parameters
Name	Type	Description
s	STRING
i	INT
j	INT

Return values
Name	Type	Description
c	INT

codes()

Short description

Returns values so that the construction for p, c in utf8.codes(s) do body end will iterate over all characters in string s, with p being the position (in bytes) and c the code point of each character. It raises an error if it meets any invalid byte sequence.

Parameters
Name	Type	Description
s	STRING

Return values
Name	Type	Description
p	INT
c	INT

len()

Short description

Returns the number of UTF-8 characters in string s that start between positions i and j (both inclusive). The default for i is 1 and for j is -1. If it finds any invalid byte sequence, returns a false value plus the position of the first invalid byte.

Parameters
Name	Type	Description
s	STRING
i	INT
j	INT

Return values
Name	Type	Description
len	INT

offset()

Short description

Returns the position (in bytes) where the encoding of the n-th character of s (counting from position i) starts. A negative n gets characters before position i. The default for i is 1 when n is non-negative and ##s + 1 otherwise, so that utf8.offset(s, -n) gets the offset of the n-th character from the end of the string. If the specified character is neither in the subject nor right after its end, the function returns nil. As a special case, when n is 0 the function returns the start of the encoding of the character that contains the i-th byte of s. This function assumes that s is a valid UTF-8 string.

Parameters
Name	Type	Description
s	STRING
n	INT
i	INT

Return values
Name	Type	Description
offset	INT

Log

Short description

Provides logging capabilities for Apps.

Overview

fine(), finer(), finest(), info(), isLogable(), setConsoleMode(), setFileMode(), setLevel(), severe(), warning()

Functions

fine()

Short description

Logs a message with level "FINE"

Parameters
Name	Type	Description
msg	STRING	The message to print out

Sample

Log.fine("My message")

finer()

Short description

Logs a message with level "FINER"

Parameters
Name	Type	Description
msg	STRING	The message to print out

Sample

Log.finer("My message")

finest()

Short description

Logs a message with level "FINEST"

Parameters
Name	Type	Description
msg	STRING	The message to print out

Sample

Log.finest("My message")

info()

Short description

Logs a message with level "INFO"

Parameters
Name	Type	Description
msg	STRING	The message to print out

Sample

Log.info("My message")

isLogable()

Short description

Returns true if the logging on the specified level is enabled. This is useful to don’t create big log outputs if the logging is disabled and log output would not be used. Only interesting for log levels smaller than warning, because warning and severe output always is needed.

Parameters
Name	Type	Description
level	ENUM Level	The level

Return values
Name	Type	Description
isLogable	BOOL	True if the logging on the specified level is enabled

setConsoleMode()

Short description

Sets the logging handling to console mode (=default). This overwrites all other modes; only one mode can be assigned to the App’s logger.

Sample

Log.setConsoleMode()

setFileMode()

Short description

Sets the logging handling to file mode. This overwrites all other modes; only one mode can be assigned to the App’s logger. The writing of the logs to the logfile is done asynchronously in the background. The maximum number of logs in the queue for writing to file is 128 for each app. If the log queue is full, the new log is thrown away. The logfile will contain a "Some log messages were lost"-string if this happened. In this case the rate of log production has to be reduced by the app. When the maximum file size is reached, the file is divided into two halves: The first half(old entries) is discarded, the second half is shifted to the beginning of the file, so new log entries can be appended at the end. Note that it depends on the underlying operating system if the logged file can be accessed while it is written. If you want to open the logged file for reading, set the logger to another file or to another mode first. Accessing files is restricted to the public/ or private/ folder, so you may only use file paths starting with either public/ or private/.

Parameters
Name	Type	Description
fileName	STRING	File name inside the public or private folder
maxFileSize	INT	Maximum file size in range of 1024 (1 kB) to 104857600 (100 MB)

Return values
Name	Type	Description
success	BOOL	true when setting was successful

Sample

Log.setFileMode("private/log.txt", 1048576)

setLevel()

Short description

Sets the logging level for the current App

Parameters
Name	Type	Description
level	ENUM Level	The level

Sample

Log.setLevel("INFO")

severe()

Short description

Logs a message with level "SEVERE"

Parameters
Name	Type	Description
msg	STRING	The message to print out

Sample

Log.severe("My message")

warning()

Short description

Logs a message with level "WARNING"

Parameters
Name	Type	Description
msg	STRING	The message to print out

Sample

Log.warning("My message")

Log.Handler

Short description

Handlers are used to connect one or more loggers to one or more endpoints, the so-called 'sinks'. A sink can be either a file, a callback function or the AppStudio console. Every handler can be attached to an arbitrary number of loggers (local, shared or the engine logger) and an arbitrary number of sinks. However, there is only one global engine logger and only one console sink because AppStudio does not offer multiple consoles. To apply the configuration on a handler, the applyConfig() function must be called. It must also be called after making changes to an already installed handler, e.g. when changing the log level. You can also add callback sinks which use callback functions with the following signature: function myHandlerFunction(message, path, level, timestamp, appName, appPosition, sourceApi) print(message) end The parameters appName, appPosition and sourceApi contain the name of the app, file and line position in the app source code and the name of the API the log was sent from. If this information is not available, the corresponding strings are empty. handler = Log.Handler.create() handler:attachToLogger("App1.myLogger") handler:attachToSharedLogger("mySharedLogger") handler:addFileSink("private/log.txt", 1000000) handler:addCallbackSink("myHandlerFunction") handler:setConsoleSinkEnabled(true) handler:setLevel("WARNING") handler:applyConfig()

Overview

addCallbackSink(), addFileSink(), applyConfig(), attachToEngineLogger(), attachToLogger(), attachToSharedLogger(), create(), setConsoleSinkEnabled(), setLevel()

Functions

addCallbackSink()

Short description

Adds a callback sink to the handler. The signature is as follows: function myHandlerFunction(message, path, level, timestamp, appName, appPosition, sourceApi) print(message) end The parameters appName, appPosition and sourceApi contain the name of the app, file and line position in the app source code and the name of the API the log was sent from. If this information is not available, the corresponding strings are empty.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
callback	STRING	The callback to be triggered when a message is dispatched

Sample

function myHandlerFunction(message, path, level, timestamp, appName, appPosition, sourceApi)
  print(message)
end
Log.Handler.addCallbackSink(handle, "myHandlerFunction")

addFileSink()

Short description

Adds a file sink to the handler.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
filePath	STRING	Path to the log file
fileSize	INT	Maximum size of the log file before truncating. Has to be in the range [1024,104857600].

Return values
Name	Type	Description
success	BOOL	True if file sink was added, false if an error occurred

Sample

Log.Handler.addFileSink(handle, "private/my.log", 1000000)

applyConfig()

Short description

Applies the handle config. This must be called in order to install the low-level handlers with the configuration set on the handle. You must also call it to update the handler after changing settings.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use

Sample

Log.Handler.applyConfig(handle)

attachToEngineLogger()

Short description

Attaches handler to the engine logger.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use

Sample

Log.Handler.attachToEngineLogger(handle)

attachToLogger()

Short description

Attaches handler to an app-local logger.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
appPath	STRING	Path of the app logger in the form AppName.LocalLoggerName

Sample

Log.Handler.attachToLogger(handle, "AppName.LoggerName")

attachToSharedLogger()

Short description

Attaches handler to a shared logger.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
loggerName	STRING	Name of the logger

Sample

Log.Handler.attachToSharedLogger(handle, "LoggerName")

create()

Short description

Creates a new Log.Handler instance.

Return values
Name	Type	Description
handle	HANDLE	The new instance

Sample

local handle = Log.Handler.create()

setConsoleSinkEnabled()

Short description

Enables/disables forwarding to AppStudio console.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
enabled	BOOL	True to enable forwarding to AppStudio console, false to disable

Sample

Log.Handler.setConsoleSinkEnabled(handle, true)

setLevel()

Short description

Sets the logging level of the handler.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
level	ENUM Level	Log level

Sample

Log.Handler.setLevel(handle, WARNING)

Log.Logger

Short description

App-local logger which belongs to the app that creates it. Messages can be logged to the logger by using the functions named after the log levels (info, warning, severe, …). To get output from the logger, a handler must be attached to it and connected to a sink. See Log.Handler for more information. logger = Log.Logger.create("myLogger") logger:warning("This is a warning")

Overview

create(), fine(), finer(), finest(), info(), isLoggable(), setLevel(), severe(), warning()

Functions

create()

Short description

Creates a new Log.Logger instance.

Parameters
Name	Type	Description
loggerName	STRING	Name of the logger

Return values
Name	Type	Description
handle	HANDLE	The new instance

Sample

local handle = Log.Logger.create("loggerName")

fine()

Short description

Logs a message with level "FINE"

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
msg	STRING	The message to print out

Sample

Log.Logger.fine(handle, "My message")

finer()

Short description

Logs a message with level "FINER"

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
msg	STRING	The message to print out

Sample

Log.Logger.finer(handle, "My message")

finest()

Short description

Logs a message with level "FINEST"

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
msg	STRING	The message to print out

Sample

Log.Logger.finest(handle, "My message")

info()

Short description

Logs a message with level "INFO"

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
msg	STRING	The message to print out

Sample

Log.Logger.info(handle, "My message")

isLoggable()

Short description

Check whether a message with a certain log level will be forwarded with the current level setting or not.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
level	ENUM Level	Log level

Return values
Name	Type	Description
loggable	BOOL	True if loggable, false if not

Sample

loggable = Log.Logger.isLoggable(handle, "INFO")

setLevel()

Short description

Sets the logging level of the logger.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
level	ENUM Level	Log level

Sample

Log.Logger.setLevel(handle, "WARNING")

severe()

Short description

Logs a message with level "SEVERE"

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
msg	STRING	The message to print out

Sample

Log.Logger.severe(handle, "My message")

warning()

Short description

Logs a message with level "WARNING"

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
msg	STRING	The message to print out

Sample

Log.Logger.warning(handle, "My message")

Log.SharedLogger

Short description

Shared logger which can be accessed from any app. The handle created does not 'own' the logger. Messages can be logged to the logger by using the functions named after the log levels (info, warning, severe, …). To get output from the logger, a handler must be attached to it and connected to a sink. See Log.Handler for more information. logger = Log.SharedLogger.create("mySharedLogger") logger:warning("This is a warning")

Overview

create(), fine(), finer(), finest(), info(), isLoggable(), setLevel(), severe(), warning()

Functions

create()

Short description

Creates a new Log.SharedLogger instance.

Parameters
Name	Type	Description
loggerName	STRING	Name of the logger

Return values
Name	Type	Description
handle	HANDLE	The new instance

Sample

local handle = Log.SharedLogger.create("loggerName")

fine()

Short description

Logs a message with level "FINE"

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
msg	STRING	The message to print out

Sample

Log.SharedLogger.fine(handle, "My message")

finer()

Short description

Logs a message with level "FINER"

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
msg	STRING	The message to print out

Sample

Log.SharedLogger.finer(handle, "My message")

finest()

Short description

Logs a message with level "FINEST"

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
msg	STRING	The message to print out

Sample

Log.SharedLogger.finest(handle, "My message")

info()

Short description

Logs a message with level "INFO"

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
msg	STRING	The message to print out

Sample

Log.SharedLogger.info(handle, "My message")

isLoggable()

Short description

Check whether a message with a certain log level will be forwarded with the current level setting or not.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
level	ENUM Level	Log level

Return values
Name	Type	Description
loggable	BOOL	True if loggable, false if not

Sample

loggable = Log.SharedLogger.isLoggable(handle, "INFO")

setLevel()

Short description

Sets the logging level of the logger.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
level	ENUM Level	Log level

Sample

Log.SharedLogger.setLevel(handle, "WARNING")

severe()

Short description

Logs a message with level "SEVERE"

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
msg	STRING	The message to print out

Sample

Log.SharedLogger.severe(handle, "My message")

warning()

Short description

Logs a message with level "WARNING"

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
msg	STRING	The message to print out

Sample

Log.SharedLogger.warning(handle, "My message")

MachineLearning

Short description

Machine learning tools for data understanding and prediction. The Machine Learning API trains classifiers and makes predictions on samples formed by collecting measurements of data as rows in a matrix. Helpers to partition data into training and evaluation set and other convenience functions to manipulate the raw dataset are also included. Classifiers in general support both regression and classification tasks. The selection is made when creating the dataset. Algorithms included - DataSet container for labeled samples. - Classifiers: Neural net, Random Forest, k-Nearest Neighbor, Support Vector Machines, Bayes, Fisher Linear Discriminant - Data dimensionality reduction: Principal Component Analysis (PCA), k-Means clustering - Methods for evaluating classifier accuracy - Methods for data statistics, selection and preconditioning.

Overview

MachineLearning.Bayes

Short description

Bayes, or as it is sometimes known, Normal Bayes Classifier, is a really simple classifier. It has no parameters and tries to separate classes by assuming normal distribution within each feature. For data that is approximately Gaussian this classifier works well and is quite quick to evaluate.

Overview

clear(), create(), getAccuracy(), getFeatureCount(), isTrained(), load(), predict(), save(), toString(), train()

Functions

clear()

Short description

Clear internal data of the classifier.

Parameters
Name	Type	Description
bayes	HANDLE	The classifier instance to use.

Sample

MachineLearning.Bayes.clear(bayes)

create()

Short description

Creates a new Bayes classifier.

Return values
Name	Type	Description
bayes	HANDLE	The new Bayes handle

Sample

bayes = MachineLearning.Bayes.create()

getAccuracy()

Short description

Evaluate a classifier against a DataSet object by computing the predicted class and comparing it to the label supplied in the DataSet object. The "accuracy" returned will be the amount of correctly classified samples divided by the total amount of samples. The second output, the "confusionMatrix", is a NxN matrix. The final return value is a vector. This vector tells us what original label correspond to what row and column in the confusion matrix. In the NxN confusion matrix contains classification statistics. Each row corresponds to a label input and each column to a classification output. That is, if all classes have been correctly classified, there should only be non-zero elements along the diagonal of this matrix. For example a matrix of the following format C = [3 1, 2 4] labels = {1, 2} This means that the model had labels 1 and 2. For these labels the classification was tested on a total of 3+1+2+4 = 10 samples. Out of these 3+2 = 5 were classified as label one and 1+4 = 5 as label two. However, there were actually 3+1 = 4 samples of type one and 2+4 = 6 of type two in the input. To calculate the accuracy sum the diagonal, 3 + 4 = 7 and divide by the total amount of samples 10, which in this case gives an accuracy of 70%. It can also be useful to analyze other properties of this matrix. In this case inputs of type 2 are more likely to be classified as type 1 than type 1 being classified as type 2.

Parameters
Name	Type	Description
bayes	HANDLE	The classifier instance to use.
dataSet	OBJECT MachineLearning.DataSet	The dataset to use

Return values
Name	Type	Description
accuracy	FLOAT	The accuracy rate. Computed as correct classifications divided by total amount of samples.
confusionMatrix	OBJECT Matrix	Confusion matrix for dataset and classifier.
confusionMatrixLabels	INT	The label key for the confusion matrix.

Sample

accuracy, confusionMatrix = MachineLearning.Bayes.getAccuracy(bayes, dataSet)

getFeatureCount()

Short description

Use to check what feature size the classifier was trained on. A classifier can only be used on new data with the same amount of features.

Parameters
Name	Type	Description
bayes	HANDLE	The classifier instance to use.

Return values
Name	Type	Description
featureCount	INT	The amount of features per sample.

Sample

trained = MachineLearning.Bayes.getFeatureCount(bayes)

isTrained()

Short description

Use to check if classifier has been trained successfully. If a classifier is trained it can be used to predict.

Parameters
Name	Type	Description
bayes	HANDLE	The classifier instance to use.

Return values
Name	Type	Description
trained	BOOL	True if the classifier is trained.

Sample

trained = MachineLearning.Bayes.isTrained(bayes)

load()

Short description

Load a Bayes classifier from disk.

Parameters
Name	Type	Description
path	STRING	The path to the classifier

Return values
Name	Type	Description
bayes	HANDLE	The Bayes handle to the loaded object.

Sample

bayes = MachineLearning.Bayes.load(path)

predict()

Short description

Classify a sample using the trained classifier.

Parameters
Name	Type	Description
bayes	HANDLE	The classifier instance to use.
sample	OBJECT Matrix	A sample or a set of samples that are to be classified. Each row of the input matrix is considered one sample.

Return values
Name	Type	Description
class	FLOAT	Predicted class output from the classifier. In case of a single sample input it’s a single value. For multi row input it’s a vector of class labels.

Sample

class = MachineLearning.Bayes.predict(bayes, sample)

save()

Short description

Save a Bayes classifier to disk.

Parameters
Name	Type	Description
bayes	HANDLE	The classifier instance to use
path	STRING	The path at which to store the classifier

Return values
Name	Type	Description
success	BOOL	True if the file was successfully stored, false if storing failed.

Sample

success = MachineLearning.Bayes.save(bayes, path)

toString()

Short description

Get a brief string description of the classifier. This is equal to the text shown in the debugger.

Parameters
Name	Type	Description
bayes	OBJECT MachineLearning.Bayes	The input classifier data

Return values
Name	Type	Description
string	STRING	Description of the classifier

Sample

print("Description: " .. MachineLearning.Bayes.toString(bayes))

train()

Short description

Perform training on data supplied in a DataSet object.

Parameters
Name	Type	Description
bayes	HANDLE	The classifier instance to use
dataSet	OBJECT MachineLearning.DataSet	Input dataset

Return values
Name	Type	Description
success	BOOL	True if classifier was successfully trained.

Sample

success = MachineLearning.Bayes.train(bayes, dataSet)

MachineLearning.DataSet

Short description

Training data container for classical machine learning applications. Stores samples and corresponding labels for input to different classifiers. It is not intended for use together with DeepNeuralNetwork applications. Samples are always floating point values, but labels are integer values for classification tasks and floating point values for regression tasks. It’s possible to also supply weights per sample which some algorithms make use of during training.

Functions

append()

Short description

Append one or multiple samples to the internal list of samples.

Parameters
Name	Type	Description
dataSet	OBJECT MachineLearning.DataSet	The input dataset
samples	OBJECT Matrix	Training sample(s). Each row is considered a separate sample. To add more samples at the same time use a matrix of multiple rows.
labels	AUTO	Training label(s). If all samples belong to the same class send a single label value. Otherwise there should be one sample per row in the samples matrix.
weight	OBJECT Matrix	Optional weights for each sample. This matrix must be single column and have as many rows as samples

Return values
Name	Type	Description
success	BOOL	True if data was successfully added.

Sample

MachineLearning.DataSet.append(dataSet, sample, label)

calculateNormalization()

Short description

Calculate a matrix with the mean and standard deviation for each feature. This matrix is convenient to use as input for normalizing dataset objects as well as raw matrices for example before classification. The matrix consist of the mean and standard deviation for each sample. Means are in the first row, standard deviations in the second.

Parameters
Name	Type	Description
dataSet	OBJECT MachineLearning.DataSet	The input dataset

Return values
Name	Type	Description
normalization	OBJECT Matrix	The normalization matrix.

Sample

normalization = MachineLearning.DataSet.calculateNormalization(dataSet)

calculateProjection()

Short description

Calculate a matrix with the means of each feature in the first row and principal component eigen vectors in the following rows. The total height of the returned matrix minus one corresponds to the output dimension after projection.

Parameters
Name	Type	Description
dataSet	OBJECT MachineLearning.DataSet	The input dataset
maxDimensions	INT	Set this value to determine the dimensions of the output. To keep all set to 0 or the original feature size.
retainVariance	FLOAT	Set this to select how much of the original signal to keep. If set to 0.5 it means that at least 50% of the signal energy remains after projection.

Return values
Name	Type	Description
projection	OBJECT Matrix	The projection matrix.

Sample

projection = MachineLearning.DataSet.calculateProjection(dataSet, maxDimensions, retainVariance)

calculateStatistics()

Short description

Calculate and return statistics for the dataset object.

Parameters
Name	Type	Description
dataSet	OBJECT MachineLearning.DataSet	The input dataset

Return values
Name	Type	Description
mean	FLOAT	A vector containing the mean for each feature.
std	FLOAT	A vector containing the standard deviation for each feature.
min	FLOAT	A vector containing the minimum value for each feature.
max	FLOAT	A vector containing the maximum value for each feature.

Sample

mean, std, min, max = MachineLearning.DataSet.calculateStatistics(dataSet)

clear()

Short description

Remove all internally stored samples. Clearing out samples reduces memory usage and can be useful when large datasets are used for training.

Parameters
Name	Type	Description
dataSet	OBJECT MachineLearning.DataSet	The input dataset

Sample

MachineLearning.DataSet.clear(dataSet)

create()

Short description

Creates a new DataSet object

Parameters
Name	Type	Description
labelType	ENUM LabelType	Create a dataset of the selected type.

Return values
Name	Type	Description
dataSet	OBJECT MachineLearning.DataSet	The new dataset.

Sample

dataSet = MachineLearning.DataSet.create("CLASSIFICATION")

getFeature()

Short description

Return a feature from the sample set.

Parameters
Name	Type	Description
dataSet	OBJECT MachineLearning.DataSet	The input dataset
index	INT	The index into the dataset. If left out all all features are returned. This is the same getSample without index.

Return values
Name	Type	Description
sample	OBJECT Matrix	The matrix corresponding to the selected feature index or in case index is left out all features. Each feature is a separate column.

Sample

feature = MachineLearning.DataSet.getFeature(dataSet, index)

getFeatureCount()

Short description

Return the number of values stored per sample. This is the same as the number of columns in each sample that has been added.

Parameters
Name	Type	Description
dataSet	OBJECT MachineLearning.DataSet	The input dataset

Return values
Name	Type	Description
featureCount	INT	The amount of features

Sample

featureCount = MachineLearning.DataSet.getFeatureCount(dataSet)

getLabel()

Short description

Return label for a sample in the loaded set.

Parameters
Name	Type	Description
dataSet	OBJECT MachineLearning.DataSet	The input dataset
index	INT	The index into the dataset. If left out all labels are returned.

Return values
Name	Type	Description
label	AUTO	The label corresponding to the selected sample index or all labels if no index is supplied.

Sample

label = MachineLearning.DataSet.getLabel(dataSet, index)

getSample()

Short description

Return a sample from the sample set.

Parameters
Name	Type	Description
dataSet	OBJECT MachineLearning.DataSet	The input dataset
index	INT	The index into the dataset. If left out all samples are returned. This is the same as getFeature without index.

Return values
Name	Type	Description
sample	OBJECT Matrix	The matrix corresponding to the selected sample index or in case index is left out all samples. Each sample is a separate row.

Sample

sample = MachineLearning.DataSet.getSample(dataSet, index)

getSampleCount()

Short description

Return the amount of samples currently stored in the dataset.

Parameters
Name	Type	Description
dataSet	OBJECT MachineLearning.DataSet	The input dataset

Return values
Name	Type	Description
samplesCount	INT	The amount of samples

Sample

samplesCount = MachineLearning.DataSet.getSampleCount(dataSet)

getSubset()

Short description

Return a new dataset object of a selected subset of the original dataset.

Parameters
Name	Type	Description
dataSet	OBJECT MachineLearning.DataSet	The input dataset
start	INT	The start index at which to start extracting samples.
count	INT	The amount of samples to extract. If left out all samples after start will be extracted.

Return values
Name	Type	Description
dataSet	OBJECT MachineLearning.DataSet	The new dataset consisting of only selected samples.

Sample

sample = MachineLearning.DataSet.getSubset(dataSet, start, count)

getSubsetInterval()

Short description

Return a new dataset object of a selected subset of the original dataset. This function allows extraction of an interval of label values in case the LabelType is REGRESSION.

Parameters
Name	Type	Description
dataSet	OBJECT MachineLearning.DataSet	The input dataset
minValue	FLOAT	The smallest value of a label to keep in the output.
maxValue	FLOAT	The largest value of a label to keep in the output.

Return values
Name	Type	Description
dataSet	OBJECT MachineLearning.DataSet	The new dataset consisting of all samples with labels in the specified region.

Sample

sample = MachineLearning.DataSet.getSubsetInterval(dataSet, minValue, maxValue)

getSubsetLabels()

Short description

Return a new dataset object of a selected subset of the original dataset. This function allows the extraction of specific labels in case the LabelType is CLASSIFICATION.

Parameters
Name	Type	Description
dataSet	OBJECT MachineLearning.DataSet	The input dataset
labels	INT	A vector of labels to keep in the output.

Return values
Name	Type	Description
dataSet	OBJECT MachineLearning.DataSet	The new dataset consisting of all samples with the selected labels.

Sample

sample = MachineLearning.DataSet.getSubsetLabels(dataSet, labels)

getType()

Short description

Returns the type of the data set, either CLASSIFICATION or REGRESSION.

Parameters
Name	Type	Description
dataSet	CONST_OBJECT MachineLearning.DataSet	The input dataset.

Return values
Name	Type	Description
type	ENUM LabelType	The type of the data set

Sample

type = MachineLearning.getType(dataSet)

getWeight()

Short description

Return weight for a sample in the loaded set.

Parameters
Name	Type	Description
dataSet	OBJECT MachineLearning.DataSet	The input dataset
index	INT	The index into the dataset. If left out all weights are returned.

Return values
Name	Type	Description
weight	AUTO	The weight corresponding to the selected sample index or all weights if no index is supplied.

Sample

weight = MachineLearning.DataSet.getWeight(dataSet, index)

normalize()

Short description

Apply a normalization matrix to a dataset object or another matrix. In both cases the dimensions must be compatible. Eg. the feature size of the dataset object or the amount of columns of the matrix must be equal to the columns of the normalization matrix.

Parameters
Name	Type	Description
source	OBJECT [API:DataFormat:]	Either a dataset object or a matrix.
normalization	OBJECT Matrix	A normalization matrix. Can be created using calculateNormalization or by manual composition.

Return values
Name	Type	Description
normalized	OBJECT [API:DataFormat:]	A normalized version of the source input.

Sample

normalized = MachineLearning.DataSet.normalize(source, normalization)

project()

Short description

Apply a projection matrix to a dataset object or another matrix. In both cases the dimensions must be compatible. Eg. the feature size of the dataset object or the amount of columns of the matrix must be equal to the columns of the projection matrix.

Parameters
Name	Type	Description
source	OBJECT [API:DataFormat:]	Either a dataset object or a matrix.
projection	OBJECT Matrix	A projection matrix. Can be created using calculateProjection or by manual composition.

Return values
Name	Type	Description
projected	OBJECT [API:DataFormat:]	The projected version of the source input.

Sample

projected = MachineLearning.DataSet.project(source, projection)

split()

Short description

Split a dataset object into two parts. The amount of samples in the larger set will be the same as the amount of samples in the smaller set times the input "factor". This means if factor is set to 3 that the first dataset object will be 3 times larger than the second. The sample selection is automatically randomized. To turn of randomization set the optional parameter "randomize" to false.

Parameters
Name	Type	Description
dataSet	OBJECT MachineLearning.DataSet	The input dataset
factor	INT	The amount of samples in the major set compared to the minor set.
randomize	BOOL	Select if samples should be randomized before split. Default is true.

Return values
Name	Type	Description
major	OBJECT MachineLearning.DataSet	A new dataset containing the larger part of the samples.
minor	OBJECT MachineLearning.DataSet	A new dataset containing the smaller part of the samples.

Sample

major, minor = MachineLearning.DataSet.split(dataSet, 3)

toString()

Short description

Get a brief string description of the dataset. This is equal to the text shown in the debugger to describe the dataset.

Parameters
Name	Type	Description
dataSet	OBJECT MachineLearning.DataSet	The input dataset

Return values
Name	Type	Description
string	STRING	Description of the dataset

Sample

print("Description: " .. MachineLearning.DataSet.toString(dataSet))

MachineLearning.Fisher

Short description

Fisher’s linear discriminant, sometimes called Linear Discriminant Analysis (LDA) is a method to find a vector which linearly separates two classes in an optimal way. This vector is found so that samples from different classes projected onto this vector end up as far apart a possible. For this reason Fisher can be used to understand what features of a data set have the most discriminating effect by looking at this vector. This is useful when trying to reduce the feature size input to another classifier without loosing too much performance.

Overview

clear(), create(), getAccuracy(), getFeatureCount(), getProjectionVector(), isTrained(), load(), predict(), save(), toString(), train()

Functions

clear()

Short description

Clear internal data of the classifier.

Parameters
Name	Type	Description
fisher	HANDLE	The classifier instance to use.

Sample

MachineLearning.Fisher.clear(fisher)

create()

Short description

Creates a handle for Fisher’s linear discriminant.

Return values
Name	Type	Description
fisher	HANDLE	The new Fisher handle

Sample

lda = MachineLearning.Fisher.create()

getAccuracy()

Short description

Parameters
Name	Type	Description
fisher	HANDLE	The classifier instance to use.
dataSet	OBJECT MachineLearning.DataSet	The dataset to use

Return values
Name	Type	Description
accuracy	FLOAT	The accuracy rate. Computed as correct classifications divided by total amount of samples.
confusionMatrix	OBJECT Matrix	Confusion matrix for dataset and classifier.
confusionMatrixLabels	INT	The label key for the confusion matrix.

Sample

accuracy, confusionMatrix = MachineLearning.Fisher.getAccuracy(fisher, dataSet)

getFeatureCount()

Short description

Use to check what feature size the classifier was trained on. A classifier can only be used on new data with the same amount of features.

Parameters
Name	Type	Description
fisher	HANDLE	The classifier instance to use.

Return values
Name	Type	Description
featureCount	INT	The amount of features per sample.

Sample

trained = MachineLearning.Fisher.getFeatureCount(fisher)

getProjectionVector()

Short description

Returns the estimated projection direction for this classifier. This can be used to better understand what features are distinguishing when separating the objects.

Parameters
Name	Type	Description
fisher	HANDLE	The classifier instance to use.

Return values
Name	Type	Description
vector	FLOAT	A vector with the coefficients for projection.

Sample

vector = MachineLearning.Fisher.getProjectionVector(fisher)

isTrained()

Short description

Use to check if classifier has been trained successfully. If a classifier is trained it can be used to predict.

Parameters
Name	Type	Description
fisher	HANDLE	The classifier instance to use.

Return values
Name	Type	Description
trained	BOOL	True if the classifier is trained.

Sample

trained = MachineLearning.Fisher.isTrained(fisher)

load()

Short description

Load a Fisher classifier from disk.

Parameters
Name	Type	Description
path	STRING	The path to the classifier

Return values
Name	Type	Description
fisher	HANDLE	The Fisher handle to the loaded object.

Sample

fisher = MachineLearning.Fisher.load(path)

predict()

Short description

Classify a sample using the trained classifier.

Parameters
Name	Type	Description
fisher	HANDLE	The classifier instance to use.
sample	OBJECT Matrix	A sample or a set of samples that are to be classified. Each row of the input matrix is considered one sample.

Return values
Name	Type	Description
class	FLOAT	Predicted class output from the classifier. In case of a single sample input it’s a single value. For multi row input it’s a vector of class labels.

Sample

class = MachineLearning.Fisher.predict(fisher, sample)

save()

Short description

Save a Fisher classifier to disk.

Parameters
Name	Type	Description
fisher	HANDLE	The classifier instance to use
path	STRING	The path at which to store the classifier

Return values
Name	Type	Description
success	BOOL	True if the file was successfully stored, false if storing failed.

Sample

success = MachineLearning.Fisher.save(fisher, path)

toString()

Short description

Get a brief string description of the classifier. This is equal to the text shown in the debugger.

Parameters
Name	Type	Description
fisher	OBJECT MachineLearning.Fisher	The input classifier data

Return values
Name	Type	Description
string	STRING	Description of the classifier

Sample

print("Description: " .. MachineLearning.Fisher.toString(fisher))

train()

Short description

Perform training on data supplied in a DataSet object.

Parameters
Name	Type	Description
fisher	HANDLE	The classifier instance to use
dataSet	OBJECT MachineLearning.DataSet	Input dataset

Return values
Name	Type	Description
success	BOOL	True if classifier was successfully trained.

Sample

success = MachineLearning.Fisher.train(fisher, dataSet)

MachineLearning.KMeansClustering

Short description

k-Means Clustering is a technique mainly used to find structure in unordered data. It’s an iterative method which tries to group samples into clusters in a two step process. First a start solution is created by randomizing a number of cluster centers. Then features are assigned to clusters based on the feature distance to the cluster centers and secondly the center of each cluster is updated based on its feature members. This is iterated for a selectable number of cycles. Note that KMeansClustering in reality is a clustering algorithm and not really a classifier. It can be used for classification by checking what cluster a sample is closest to after training. Because of the clustering nature the default behavior is that the labels of the input data is updated with the result of the clustering operation. To disable this behavior set "updateInput" to false in setParameters.

Overview

clear(), create(), getClusterCenters(), getCompactness(), getFeatureCount(), isTrained(), load(), predict(), save(), setParameters(), toString(), train()

Functions

clear()

Short description

Clear internal data of the classifier.

Parameters
Name	Type	Description
km	HANDLE	The classifier instance to use.

Sample

MachineLearning.KMeansClustering.clear(km)

create()

Short description

Creates a new KMeansClustering object.

Return values
Name	Type	Description
km	HANDLE	The new KMeansClustering handle

Sample

km = MachineLearning.KMeansClustering.create()

getClusterCenters()

Short description

Get the resulting cluster centers for evaluation of the result.

Parameters
Name	Type	Description
km	HANDLE	The classifier instance to use.

Return values
Name	Type	Description
clusters	OBJECT Matrix	The cluster centers with one position per row.

Sample

clusters = MachineLearning.KMeansClustering.getClusterCenters(km)

getCompactness()

Short description

Get the compactness of the clustering. This is a measure on how well classes could be separated and is calculated as the average distance from all samples to their cluster centers.

Parameters
Name	Type	Description
km	HANDLE	The classifier instance to use.

Return values
Name	Type	Description
compactness	FLOAT	The compactness of the clustering.

Sample

compactness = MachineLearning.KMeansClustering.getCompactness(km)

getFeatureCount()

Short description

Use to check what feature size the classifier was trained on. A classifier can only be used on new data with the same amount of features.

Parameters
Name	Type	Description
km	HANDLE	The classifier instance to use.

Return values
Name	Type	Description
featureCount	INT	The amount of features per sample.

Sample

trained = MachineLearning.KMeansClustering.getFeatureCount(km)

isTrained()

Short description

Use to check if classifier has been trained successfully. If a classifier is trained it can be used to predict.

Parameters
Name	Type	Description
km	HANDLE	The classifier instance to use.

Return values
Name	Type	Description
trained	BOOL	True if the classifier is trained.

Sample

trained = MachineLearning.KMeansClustering.isTrained(km)

load()

Short description

Load a KMeansClustering classifier from disk.

Parameters
Name	Type	Description
path	STRING	The path to the classifier

Return values
Name	Type	Description
km	HANDLE	The KMeansClustering handle to the loaded object.

Sample

km = MachineLearning.KMeansClustering.load(path)

predict()

Short description

Classify a sample using the trained classifier.

Parameters
Name	Type	Description
km	HANDLE	The classifier instance to use.
sample	OBJECT Matrix	A sample or a set of samples that are to be classified. Each row of the input matrix is considered one sample.

Return values
Name	Type	Description
class	FLOAT	Predicted class output from the classifier. In case of a single sample input it’s a single value. For multi row input it’s a vector of class labels.

Sample

class = MachineLearning.KMeansClustering.predict(km, sample)

save()

Short description

Save a KMeansClustering classifier to disk.

Parameters
Name	Type	Description
km	HANDLE	The classifier instance to use
path	STRING	The path at which to store the classifier

Return values
Name	Type	Description
success	BOOL	True if the file was successfully stored, false if storing failed.

Sample

success = MachineLearning.KMeansClustering.save(km, path)

setParameters()

Short description

Set parameters for how training should be done.

Parameters
Name	Type	Description
km	HANDLE	The classifier instance to use
numberOfClusters	INT	The number of clusters to fit to data (number of classes).
initMethod	ENUM InitMethod	Select the way to initialize the algorithm.
iterations	INT	Select the number of iterations to run the algorithm. Default is 100.
updateInput	BOOL	Select if the labels of the dataset should be updated. Default is true.

Return values
Name	Type	Description
success	BOOL	True if successful, false if combination of parameters is unsupported.

Sample

success = MachineLearning.KMeansClustering.setParameters(km, "RANDOM")

toString()

Short description

Get a brief string description of the classifier. This is equal to the text shown in the debugger.

Parameters
Name	Type	Description
km	OBJECT MachineLearning.KMeansClustering	The input classifier data

Return values
Name	Type	Description
string	STRING	Description of the classifier

Sample

print("Description: " .. MachineLearning.KMeansClustering.toString(km))

train()

Short description

Perform training on data supplied in a DataSet object.

Parameters
Name	Type	Description
km	HANDLE	The classifier instance to use
dataSet	OBJECT MachineLearning.DataSet	Input dataset

Return values
Name	Type	Description
success	BOOL	True if classifier was successfully trained.

Sample

success = MachineLearning.KMeansClustering.train(km, dataSet)

MachineLearning.KNearestNeighbors

Short description

k Nearest Neighbors or kNN for short, is basically a voting scheme based on proximity. During training the training samples are collected and are themselves stored for later use during classification. During classification the features of a new sample are compared to features of the k closest samples from the training dataset. The classification is given by the majority vote of these k samples.

Overview

clear(), create(), getAccuracy(), getFeatureCount(), isTrained(), load(), predict(), save(), setParameters(), toString(), train()

Functions

clear()

Short description

Clear internal data of the classifier.

Parameters
Name	Type	Description
knn	HANDLE	The classifier instance to use.

Sample

MachineLearning.KNearestNeighbors.clear(knn)

create()

Short description

Creates a new KNearestNeighbors handle

Return values
Name	Type	Description
knn	HANDLE	The new KNearestNeighbors handle

Sample

knn = MachineLearning.KNearestNeighbors.create()

getAccuracy()

Short description

Parameters
Name	Type	Description
knn	HANDLE	The classifier instance to use.
dataSet	OBJECT MachineLearning.DataSet	The dataset to use

Return values
Name	Type	Description
accuracy	FLOAT	The accuracy rate. Computed as correct classifications divided by total amount of samples.
confusionMatrix	OBJECT Matrix	Confusion matrix for dataset and classifier.
confusionMatrixLabels	INT	The label key for the confusion matrix.

Sample

accuracy, confusionMatrix = MachineLearning.KNearestNeighbors.getAccuracy(knn, dataSet)

getFeatureCount()

Short description

Use to check what feature size the classifier was trained on. A classifier can only be used on new data with the same amount of features.

Parameters
Name	Type	Description
knn	HANDLE	The classifier instance to use.

Return values
Name	Type	Description
featureCount	INT	The amount of features per sample.

Sample

trained = MachineLearning.KNearestNeighbors.getFeatureCount(knn)

isTrained()

Short description

Use to check if classifier has been trained successfully. If a classifier is trained it can be used to predict.

Parameters
Name	Type	Description
knn	HANDLE	The classifier instance to use.

Return values
Name	Type	Description
trained	BOOL	True if the classifier is trained.

Sample

trained = MachineLearning.KNearestNeighbors.isTrained(knn)

load()

Short description

Load a KNearestNeighbors classifier from disk.

Parameters
Name	Type	Description
path	STRING	The path to the classifier

Return values
Name	Type	Description
knn	HANDLE	The KNearestNeighbors handle to the loaded object.

Sample

knn = MachineLearning.KNearestNeighbors.load(path)

predict()

Short description

Classify a sample using the trained classifier.

Parameters
Name	Type	Description
knn	HANDLE	The classifier instance to use.
sample	OBJECT Matrix	A sample or a set of samples that are to be classified. Each row of the input matrix is considered one sample.

Return values
Name	Type	Description
class	FLOAT	Predicted class output from the classifier. In case of a single sample input it’s a single value. For multi row input it’s a vector of class labels.

Sample

class = MachineLearning.KNearestNeighbors.predict(knn, sample)

save()

Short description

Save a KNearestNeighbors classifier to disk.

Parameters
Name	Type	Description
knn	HANDLE	The classifier instance to use
path	STRING	The path at which to store the classifier

Return values
Name	Type	Description
success	BOOL	True if the file was successfully stored, false if storing failed.

Sample

success = MachineLearning.KNearestNeighbors.save(knn, path)

setParameters()

Short description

Set parameters for how training should be done.

Parameters
Name	Type	Description
handle	HANDLE	The classifier instance to use
numberOfNeighbors	INT	Number of neighbors to use when calculating.

Return values
Name	Type	Description
success	BOOL	True if successful, false if combination of parameters is unsupported.

Sample

success = MachineLearning.KNearestNeighbors.setParameters(knn, 13)

toString()

Short description

Get a brief string description of the classifier. This is equal to the text shown in the debugger.

Parameters
Name	Type	Description
knn	OBJECT MachineLearning.KNearestNeighbors	The input classifier data

Return values
Name	Type	Description
string	STRING	Description of the classifier

Sample

print("Description: " .. MachineLearning.KNearestNeighbors.toString(knn))

train()

Parameters
Name	Type	Description
knn	HANDLE	The classifier instance to use
dataSet	OBJECT MachineLearning.DataSet	Input dataset

Return values
Name	Type	Description
success	BOOL	True if classifier was successfully trained.

Sample

MachineLearning.KNearestNeighbors.train(knn, dataSet)

MachineLearning.NeuralNet

Short description

A neural network also known as Artificial Neural Net (ANN) or multi-layer perceptron (MLP) is a model initially created to mimic the function of neurons. Note that this is a shallow fully connected neural network model that can be trained on device. For larger Deep Neural Networks and Convolutional Networks see the DeepNeuralNetwork API. In a neural network there is an input layer, an output layer and a number of hidden layers. The input layer typically corresponds to the input features and the output layer to the output labels. In-between these two layers is an undecided number of hidden layers. The number of layers can be selected by the length of the "hiddenLayers" vector in the setParameters function and the amount of neurons in each layer by the value at each position in this vector. The first value corresponds to the layer closest to the input. Each neuron can be thought of as a simple decision point in the graph. How the decision is made is determined through training by means of back propagation on training data and by the selection of the activation function prior to training. One special feature of the neural network is that it can be trained incrementally. That is, it’s possible to train on different DataSet objects in sequence and get a final model with the accumulated result. The limitation of this is that only new samples of the same format can be added, no new features can be introduced between increments. Be sure to use the "clear" function if incremental training is not intended!

Overview

clear(), create(), getAccuracy(), getFeatureCount(), isTrained(), load(), predict(), save(), setParameters(), toString(), train()

Functions

clear()

Short description

Clear internal data of the classifier. Use this to forget previous samples and reset all network weights.

Parameters
Name	Type	Description
nn	HANDLE	The classifier instance to use.

Sample

MachineLearning.NeuralNet.clear(nn)

create()

Short description

Creates a new NeuralNet

Return values
Name	Type	Description
nn	HANDLE	The new NeuralNet handle

Sample

nn = MachineLearning.NeuralNet.create()

getAccuracy()

Short description

Parameters
Name	Type	Description
nn	HANDLE	The classifier instance to use.
dataSet	OBJECT MachineLearning.DataSet	The dataset to use

Return values
Name	Type	Description
accuracy	FLOAT	The accuracy rate. Computed as correct classifications divided by total amount of samples.
confusionMatrix	OBJECT Matrix	Confusion matrix for dataset and classifier.
confusionMatrixLabels	INT	The label key for the confusion matrix.

Sample

accuracy, confusionMatrix = MachineLearning.NeuralNet.getAccuracy(nn, dataSet)

getFeatureCount()

Short description

Use to check what feature size the classifier was trained on. A classifier can only be used on new data with the same amount of features.

Parameters
Name	Type	Description
nn	HANDLE	The classifier instance to use.

Return values
Name	Type	Description
featureCount	INT	The amount of features per sample.

Sample

trained = MachineLearning.NeuralNet.getFeatureCount(nn)

isTrained()

Short description

Use to check if classifier has been trained successfully. If a classifier is trained it can be used to predict.

Parameters
Name	Type	Description
nn	HANDLE	The classifier instance to use.

Return values
Name	Type	Description
trained	BOOL	True if the classifier is trained.

Sample

trained = MachineLearning.NeuralNet.isTrained(nn)

load()

Short description

Load a NeuralNet classifier from disk.

Parameters
Name	Type	Description
path	STRING	The path to the classifier

Return values
Name	Type	Description
nn	HANDLE	The NeuralNet handle to the loaded object.

Sample

nn = MachineLearning.NeuralNet.load(path)

predict()

Short description

Classify a sample using the trained classifier.

Parameters
Name	Type	Description
nn	HANDLE	The classifier instance to use.
sample	OBJECT Matrix	A sample or a set of samples that are to be classified. Each row of the input matrix is considered one sample.

Return values
Name	Type	Description
class	FLOAT	Predicted class output from the classifier. In case of a single sample input it’s a single value. For multi row input it’s a vector of class labels.

Sample

class = MachineLearning.NeuralNet.predict(nn, sample)

save()

Short description

Save a NeuralNet classifier to disk.

Parameters
Name	Type	Description
nn	HANDLE	The classifier instance to use
path	STRING	The path at which to store the classifier

Return values
Name	Type	Description
success	BOOL	True if the file was successfully stored, false if storing failed.

Sample

success = MachineLearning.NeuralNet.save(nn, path)

setParameters()

Short description

Set parameters for how training should be done.

Parameters
Name	Type	Description
handle	HANDLE	The classifier instance to use
hiddenLayers	INT	A vector specifying how many hidden neurons there should be in each layer. The first entry is closest to the input layer.
activationFunction	ENUM ActivationFunction	Type of activation function to use in the perceptrons. If omitted SIGMOID is used.
weightScale	FLOAT	Sets the weight scale for back propagation calculations.
momentumScale	FLOAT	Sets the momentum scale for back propagation calculations.

Return values
Name	Type	Description
success	BOOL	True if successful, false if combination of parameters is unsupported.

Sample

success = MachineLearning.NeuralNet.setParameters(nn, {3, 4}, "SIGMOID")

toString()

Short description

Get a brief string description of the classifier. This is equal to the text shown in the debugger.

Parameters
Name	Type	Description
nn	OBJECT MachineLearning.NeuralNet	The input classifier data

Return values
Name	Type	Description
string	STRING	Description of the classifier

Sample

print("Description: " .. MachineLearning.NeuralNet.toString(nn))

train()

Short description

Perform training on data supplied in a DataSet object. Note that training is done incrementally. To start out from the beginning use "clear" or create a new NeuralNet handle.

Parameters
Name	Type	Description
nn	HANDLE	The classifier instance to use
dataSet	OBJECT MachineLearning.DataSet	Input dataset

Return values
Name	Type	Description
success	BOOL	True if classifier was successfully trained.

Sample

success = MachineLearning.NeuralNet.train(nn, dataSet)

MachineLearning.RandomForest

Short description

The random forest method is a method based on decision trees. During training multiple decision trees are created based on subsets of the training dataset. During classification each tree is evaluated on the data and the majority vote wins.

Overview

clear(), create(), getAccuracy(), getFeatureCount(), isTrained(), load(), predict(), save(), setParameters(), toString(), train()

Functions

clear()

Short description

Clear internal data of the classifier.

Parameters
Name	Type	Description
rf	HANDLE	The classifier instance to use.

Sample

MachineLearning.RandomForest.clear(rf)

create()

Short description

Creates a new RandomForest

Return values
Name	Type	Description
rf	HANDLE	The new RandomForest handle

Sample

rf = MachineLearning.RandomForest.create()

getAccuracy()

Short description

Parameters
Name	Type	Description
rf	HANDLE	The classifier instance to use.
dataSet	OBJECT MachineLearning.DataSet	The data set to use

Return values
Name	Type	Description
accuracy	FLOAT	The accuracy rate. Computed as correct classifications divided by total amount of samples.
confusionMatrix	OBJECT Matrix	Confusion matrix for data set and classifier.
confusionMatrixLabels	INT	The label key for the confusion matrix.

Sample

accuracy, confusionMatrix = MachineLearning.RandomForest.getAccuracy(rf, dataSet)

getFeatureCount()

Short description

Use to check what feature size the classifier was trained on. A classifier can only be used on new data with the same amount of features.

Parameters
Name	Type	Description
rf	HANDLE	The classifier instance to use.

Return values
Name	Type	Description
featureCount	INT	The amount of features per sample.

Sample

trained = MachineLearning.RandomForest.getFeatureCount(rf)

isTrained()

Short description

Use to check if classifier has been trained successfully. If a classifier is trained it can be used to predict.

Parameters
Name	Type	Description
rf	HANDLE	The classifier instance to use.

Return values
Name	Type	Description
trained	BOOL	True if the classifier is trained.

Sample

trained = MachineLearning.RandomForest.isTrained(rf)

load()

Short description

Load a RandomForest classifier from disk.

Parameters
Name	Type	Description
path	STRING	The path to the classifier

Return values
Name	Type	Description
rf	HANDLE	The RandomForest handle to the loaded object.

Sample

rf = MachineLearning.RandomForest.load(path)

predict()

Short description

Classify a sample using the trained classifier.

Parameters
Name	Type	Description
rf	HANDLE	The classifier instance to use.
sample	OBJECT Matrix	A sample or a set of samples that are to be classified. Each row of the input matrix is considered one sample.

Return values
Name	Type	Description
class	FLOAT	Predicted class output from the classifier. In case of a single sample input it’s a single value. For multi row input it’s a vector of class labels.

Sample

class = MachineLearning.RandomForest.predict(rf, sample)

save()

Short description

Save a RandomForest classifier to disk.

Parameters
Name	Type	Description
rf	HANDLE	The classifier instance to use
path	STRING	The path at which to store the classifier

Return values
Name	Type	Description
success	BOOL	True if the file was successfully stored, false if storing failed.

Sample

success = MachineLearning.RandomForest.save(rf, path)

setParameters()

Short description

Set parameters for how training should be done.

Parameters
Name	Type	Description
handle	HANDLE	The classifier instance to use
minSamplesPerNode	INT	If the number of samples in a node is less than this value the node will not be split. Default is 10.
regressionAccuracy	FLOAT	Limit to determine when to stop splitting nodes for regression trees. Default is 0.01.
activeVarCount	INT	The size of the subset of features at each tree node that are used to find the best split(s). If set to 0 it is automatically set to the square root of the number of samples.
maxCategories	INT	In cases with more than 2 classes this limitation is used to reduce computation time at the cost of precision. Use a higher value for more precise results. Default is 10.
maxTreeDepth	INT	If no other termination criteria stops the splitting this determines the maximum allowed depth of a tree. Default is 10.

Return values
Name	Type	Description
success	BOOL	True if successful, false if combination of parameters is unsupported.

Sample

success = MachineLearning.RandomForest.setParameters(rf, ...)

toString()

Short description

Get a brief string description of the classifier. This is equal to the text shown in the debugger.

Parameters
Name	Type	Description
rf	OBJECT MachineLearning.RandomForest	The input classifier data

Return values
Name	Type	Description
string	STRING	Description of the classifier

Sample

print("Description: " .. MachineLearning.RandomForest.toString(rf))

train()

Short description

Perform training on data supplied in a DataSet object.

Parameters
Name	Type	Description
rf	HANDLE	The classifier instance to use
dataSet	OBJECT MachineLearning.DataSet	Input dataset

Return values
Name	Type	Description
success	BOOL	True if classifier was successfully trained.

Sample

success = MachineLearning.RandomForest.train(rf, dataSet)

MachineLearning.SupportVectorMachine

Short description

Support Vector Machines are used to distinguish multidimensional data by creating a decision boundary that maximizes the orthogonal distance between classes. A Support Vector Machine can be configured to support non-linear cases by using a non-linear kernel. A special case of the Support Vector Machine is the single class case where a classifier can be trained on samples only from one class to learn to recognize if new samples belong to this class or not. This requires training data set with only one input class.

Overview

clear(), create(), getAccuracy(), getFeatureCount(), isTrained(), load(), predict(), save(), setParameters(), toString(), train()

Functions

clear()

Short description

Clear internal data of the classifier.

Parameters
Name	Type	Description
svm	HANDLE	The classifier instance to use.

Sample

MachineLearning.SupportVectorMachine.clear(svm)

create()

Short description

Creates a new SupportVectorMachine

Return values
Name	Type	Description
svm	HANDLE	The new SupportVectorMachine

Sample

svm = MachineLearning.SupportVectorMachine.create()

getAccuracy()

Short description

Parameters
Name	Type	Description
svm	HANDLE	The classifier instance to use.
dataSet	OBJECT MachineLearning.DataSet	The data set to use

Return values
Name	Type	Description
accuracy	FLOAT	The accuracy rate. Computed as correct classifications divided by total amount of samples.
confusionMatrix	OBJECT Matrix	Confusion matrix for data set and classifier.
confusionMatrixLabels	INT	The label key for the confusion matrix.

Sample

accuracy, confusionMatrix = MachineLearning.SupportVectorMachine.getAccuracy(svm, dataSet)

getFeatureCount()

Short description

Use to check what feature size the classifier was trained on. A classifier can only be used on new data with the same amount of features.

Parameters
Name	Type	Description
svm	HANDLE	The classifier instance to use.

Return values
Name	Type	Description
featureCount	INT	The amount of features per sample.

Sample

trained = MachineLearning.SupportVectorMachine.getFeatureCount(svm)

isTrained()

Short description

Use to check if classifier has been trained successfully. If a classifier is trained it can be used to predict.

Parameters
Name	Type	Description
svm	HANDLE	The classifier instance to use.

Return values
Name	Type	Description
trained	BOOL	True if the classifier is trained.

Sample

trained = MachineLearning.SupportVectorMachine.isTrained(svm)

load()

Short description

Load a SupportVectorMachine classifier from disk.

Parameters
Name	Type	Description
path	STRING	The path to the classifier

Return values
Name	Type	Description
svm	HANDLE	The SupportVectorMachine handle to the loaded object.

Sample

svm = MachineLearning.SupportVectorMachine.load(path)

predict()

Short description

Classify a sample using the trained classifier.

Parameters
Name	Type	Description
svm	HANDLE	The classifier instance to use.
sample	OBJECT Matrix	A sample or a set of samples that are to be classified. Each row of the input matrix is considered one sample.

Return values
Name	Type	Description
class	FLOAT	Predicted class output from the classifier. In case of a single sample input it’s a single value. For multi row input it’s a vector of class labels.

Sample

class = MachineLearning.SupportVectorMachine.predict(svm, sample)

save()

Short description

Save a SupportVectorMachine classifier to disk.

Parameters
Name	Type	Description
svm	HANDLE	The classifier instance to use
path	STRING	The path at which to store the classifier

Return values
Name	Type	Description
success	BOOL	True if the file was successfully stored, false if storing failed.

Sample

success = MachineLearning.SupportVectorMachine.save(svm, path)

setParameters()

Short description

Set parameters for how training should be done.

Parameters
Name	Type	Description
handle	HANDLE	The classifier instance to use
nu	FLOAT	Parameter commonly known as nu for Support Vector Machine optimization problems. It tweaks the flexibility/smoothing of the decision boundaries and the complexity of the final classifier. Should be a value in the range of 0 to 1.
kernelType	ENUM KernelType	Type of kernel used in SupportVectorMachine computation.
sigma	FLOAT	Standard deviation sigma for the GAUSSIAN kernel function. For the LINEAR KernelType this value is unused.
singleClass	BOOL	Select this if only samples of one class is supplied. Learns to detect anomalies from this class. Not used in the regression case.
c	FLOAT	SVM C parameter for regression problems. Not used in the classification case.

Return values
Name	Type	Description
success	BOOL	Returns true if successful.

Sample

success = MachineLearning.SupportVectorMachine.setParameters(svm, nu, kernelType, gamma)

toString()

Short description

Get a brief string description of the classifier. This is equal to the text shown in the debugger.

Parameters
Name	Type	Description
svm	OBJECT MachineLearning.SupportVectorMachine	The input classifier data

Return values
Name	Type	Description
string	STRING	Description of the classifier

Sample

print("Description: " .. MachineLearning.SupportVectorMachine.toString(svm))

train()

Short description

Perform training on data supplied in a DataSet object.

Parameters
Name	Type	Description
svm	HANDLE	The classifier instance to use
dataSet	OBJECT MachineLearning.DataSet	Input data set

Return values
Name	Type	Description
success	BOOL	True if classifier was successfully trained. Nil if dataSet is nil.

Sample

MachineLearning.SupportVectorMachine.train(svm, dataSet)

Matrix

Short description

A 2D matrix of floating-point values.

Functions

add()

Short description

Adds two matrices of the same size.

Parameters
Name	Type	Description
m1	CONST_OBJECT Matrix	The first matrix to add
m2	CONST_OBJECT Matrix	The second matrix to add

Return values
Name	Type	Description
matrix	OBJECT Matrix	The sum

Sample

local matrix = Matrix.add(m1, m2)

addConstant()

Short description

Adds the value to each matrix element.

Parameters
Name	Type	Description
matrix	OBJECT Matrix	The matrix to add to
value	FLOAT	The value to add to each element in the matrix.

Sample

Matrix.addConstant(matrix, value)

clone()

Short description

Duplicates the matrix.

Parameters
Name	Type	Description
matrix	CONST_OBJECT Matrix	The instance to use

Return values
Name	Type	Description
clonedMatrix	OBJECT Matrix	The duplicated matrix

Sample

local clonedMatrix = Matrix.clone(matrix)

concatenate()

Short description

Returns the concatenation of the two matrices.

Parameters
Name	Type	Description
m1	CONST_OBJECT Matrix	The first matrix to concatenate
m2	CONST_OBJECT Matrix	The second matrix to concatenate
concatHorizontally	BOOL	If the concatenation shall be horizontally or vertically

Return values
Name	Type	Description
concatMatrix	OBJECT Matrix	The new matrix

Sample

local concatMatrix = Matrix.concatenate(m1, m2, concatHorizontally)

create()

Short description

Creates a new matrix.

Parameters
Name	Type	Description
rows	INT	The number of rows
cols	INT	The number of columns

Return values
Name	Type	Description
matrix	OBJECT Matrix	The new matrix

Sample

local matrix = Matrix.create(rows, cols)

createFromVector()

Short description

Creates a new matrix from a vector in row-major order.

Parameters
Name	Type	Description
vector	FLOAT	The vector of elements to create the matrix from
rows	INT	The number of rows
cols	INT	The number of columns

Return values
Name	Type	Description
matrix	OBJECT Matrix	The new matrix

Sample

local matrix = Matrix.createFromVector(vector, rows, cols)

createIdentity()

Short description

Creates a new identity matrix.

Parameters
Name	Type	Description
size	INT	The number of rows and columns

Return values
Name	Type	Description
matrix	OBJECT Matrix	The new identity matrix

Sample

local matrix = Matrix.createIdentity(size)

determinant()

Short description

Returns the determinant of the matrix.

Parameters
Name	Type	Description
matrix	CONST_OBJECT Matrix	The matrix for which to calculate the determinant

Return values
Name	Type	Description
det	FLOAT	The determinant of the matrix

Sample

local det = Matrix.determinant(matrix)

getColumn()

Short description

Returns one or multiple columns of the matrix. The columns are returned as a MxK matrix, where M is the number of rows of the original matrix and K is the number of column indices in colIndex.

Parameters
Name	Type	Description
matrix	CONST_OBJECT Matrix	The matrix from which to get the columns
colIndex	INT	The index of the matrix columns

Return values
Name	Type	Description
columns	OBJECT Matrix	The wanted matrix columns

Sample

local columns = Matrix.getColumn(matrix, colIndex)

getRow()

Short description

Returns one or multiple rows of the matrix. The rows are returned as a KxN matrix, where N is the number of columns of the original matrix and K is the number of row indices in rowIndex.

Parameters
Name	Type	Description
matrix	CONST_OBJECT Matrix	The matrix from which to get the rows
rowIndex	INT	The index of the matrix rows

Return values
Name	Type	Description
rows	OBJECT Matrix	The wanted matrix rows

Sample

local rows = Matrix.getRow(matrix, rowIndex)

getSize()

Short description

Returns the number of rows and columns of the matrix.

Parameters
Name	Type	Description
matrix	CONST_OBJECT Matrix	The instance to use

Return values
Name	Type	Description
rows	INT	The number of rows in the matrix
cols	INT	The number of columns in the matrix

Sample

local rows, columns= Matrix.getSize(matrix)

getValue()

Short description

Returns the value of the indexed matrix element. The first element has index (0,0).

Parameters
Name	Type	Description
matrix	CONST_OBJECT Matrix	The matrix in which to get a value
rowIndex	INT	The row index of the matrix element
colIndex	INT	The column index of the matrix element

Return values
Name	Type	Description
value	FLOAT	The value

Sample

local value = Matrix.getValue(matrix, rowIndex, colIndex)

invert()

Short description

Returns the inverse matrix.

Parameters
Name	Type	Description
matrix	CONST_OBJECT Matrix	The instance to use

Return values
Name	Type	Description
inversedMatrix	OBJECT Matrix	The inverse matrix.

Sample

local inversedMatrix = Matrix.invert(matrix)

max()

Short description

Returns the maximum value of the matrix.

Parameters
Name	Type	Description
matrix	CONST_OBJECT Matrix	The matrix in which to find the maximum value

Return values
Name	Type	Description
max	FLOAT	The maximum value of the matrix

Sample

local max = Matrix.max(matrix)

min()

Short description

Returns the minimum value of the matrix.

Parameters
Name	Type	Description
matrix	CONST_OBJECT Matrix	The matrix in which to find the minimum value

Return values
Name	Type	Description
min	FLOAT	The minimum value of the matrix

Sample

local min = Matrix.min(matrix)

multiply()

Short description

Multiplies two matrices. The first matrix must have the same number of columns as the second matrix has rows.

Parameters
Name	Type	Description
m1	CONST_OBJECT Matrix	The first matrix to multiply
m2	CONST_OBJECT Matrix	The second matrix to multiply

Return values
Name	Type	Description
matrix	OBJECT Matrix	The matrix product

Sample

local matrix = Matrix.multiply(m1, m2)

multiplyConstant()

Short description

Multiplies each matrix element with the value.

Parameters
Name	Type	Description
matrix	OBJECT Matrix	The matrix to multiply by constant
value	FLOAT	The value with which to multiply all elements in the matrix.

Sample

Matrix.multiplyConstant(matrix, value)

norm()

Short description

Returns the Frobenius norm of the matrix, the square root of the sum of the squares of its elements.

Parameters
Name	Type	Description
matrix	CONST_OBJECT Matrix	The matrix to calculate the norm for

Return values
Name	Type	Description
norm	FLOAT	The norm of the matrix

Sample

local norm = Matrix.norm(matrix)

setAll()

Short description

Sets the whole matrix to the same value.

Parameters
Name	Type	Description
matrix	OBJECT Matrix	The matrix to set
value	FLOAT	The value with which to set the whole matrix.

Sample

Matrix.setAll(matrix, value)

setColumn()

Short description

Sets one or multiple columns of the matrix.

Parameters
Name	Type	Description
matrix	OBJECT Matrix	The matrix in which to set the columns
colIndex	INT	The indices of the matrix columns to set
newColumn	CONST_OBJECT Matrix	The new matrix columns to set

Return values
Name	Type	Description
success	BOOL	True is input is valid

Sample

Matrix.setColumn(matrix, colIndex, newColumn)

setRow()

Short description

Sets one or multiple rows of the matrix.

Parameters
Name	Type	Description
matrix	OBJECT Matrix	The matrix in which to set the rows
rowIndex	INT	The index of the matrix rows to set
newRow	CONST_OBJECT Matrix	The new matrix rows

Return values
Name	Type	Description
success	BOOL	True is input is valid

Sample

Matrix.setRow(matrix, rowIndex, newRow)

setValue()

Short description

Sets the value in the indexed matrix element. The first element has index (0,0).

Parameters
Name	Type	Description
matrix	OBJECT Matrix	The matrix in which to set a value
rowIndex	INT	The row index of the matrix element to change
colIndex	INT	The column index of the matrix element to change
value	FLOAT	The value to set

Sample

Matrix.setValue(matrix, rowIndex, colIndex, value)

solve()

Short description

Computes the least squares solution to the equation system Ax = b. A is an NxM matrix. b is an Nx1 matrix. x is an Mx1 matrix and the solution to the equation system.

Parameters
Name	Type	Description
a	CONST_OBJECT Matrix	NxM matrix describing the left side of the equation system.
b	CONST_OBJECT Matrix	Nx1 matrix describing the right side of the equation system.

Return values
Name	Type	Description
x	OBJECT Matrix	Mx1 matrix containing the solution to the equation system.
residual	FLOAT	The average error by calculating (Ax - b).norm()/b.norm().

Sample

x, residual = Matrix.solve(a, b)

subtract()

Short description

Subtracts two matrices of the same size.

Parameters
Name	Type	Description
m1	CONST_OBJECT Matrix	The first matrix
m2	CONST_OBJECT Matrix	The matrix to subtract from the first

Return values
Name	Type	Description
matrix	OBJECT Matrix	The difference

Sample

local matrix = Matrix.subtract(m1, m2)

sumColumns()

Short description

Computes the sum of each column. The column sums are returned as a 1xN row matrix.

Parameters
Name	Type	Description
matrix	CONST_OBJECT Matrix	The matrix in which to calculate the column sums

Return values
Name	Type	Description
columnSums	OBJECT Matrix	The column sums of the matrix

Sample

local columnSums = Matrix.sumColumns(matrix)

sumRows()

Short description

Computes the sum of each row. The row sums are returned as a Mx1 column matrix.

Parameters
Name	Type	Description
matrix	CONST_OBJECT Matrix	The matrix in which to calculate the row sums

Return values
Name	Type	Description
rowSums	OBJECT Matrix	The row sums of the matrix

Sample

local rowSums = Matrix.sumRows(matrix)

svd()

Short description

Computes the singular value decomposition of an NxM matrix. U is the left singular vectors and U the right singular vectors corresponding to singular values S. In both U and V vectors are in the columns of each matrix such that matrix = U*diag(S)*V^T.

Parameters
Name	Type	Description
matrix	CONST_OBJECT Matrix	Matrix to decompose.

Return values
Name	Type	Description
u	OBJECT Matrix	The left singular vectors with each vector in a column.
s	FLOAT	The singular values of the input matrix.
v	OBJECT Matrix	The right singular vectors with each vector in a column.

Sample

u, s, v = Matrix.svd(matrix)

tile()

Short description

Returns an n-by-m tiling of the matrix.

Parameters
Name	Type	Description
matrix	CONST_OBJECT Matrix	The matrix to tile
n	INT	The number of vertical repetitions
m	INT	The number of horizontal repetitions

Return values
Name	Type	Description
tileMatrix	OBJECT Matrix	The new matrix

Sample

local tileMatrix = Matrix.tile(matrix, n, m)

toImage()

Short description

Converts a matrix to a float64 image.

Parameters
Name	Type	Description
matrix	CONST_OBJECT Matrix	Matrix to convert to image.

Return values
Name	Type	Description
image	OBJECT Image	Image created from the matrix.

Sample

image = Matrix.toImage(matrix)

toPoints()

Short description

Converts a matrix to a vector of 2D or 3D points.

Parameters
Name	Type	Description
matrix	CONST_OBJECT Matrix	Matrix to convert to vector of points.
storedInColumns	BOOL	True if the points are in the columns of the matrix, false if in the rows of the matrix.

Return values
Name	Type	Description
points	OBJECT Point	Points created from the matrix.

Sample

points = Matrix.toPoints(matrix, storedInColumns)

toString()

Short description

Get a string representation of the matrix.

Parameters
Name	Type	Description
matrix	CONST_OBJECT Matrix	Input matrix

Return values
Name	Type	Description
str	STRING	String representation of the matrix

Sample

print("The matrix is: " .. Matrix.toString(matrix))

toVector()

Short description

Returns all elements of the matrix as vector in row-major order.

Parameters
Name	Type	Description
matrix	CONST_OBJECT Matrix	The matrix

Return values
Name	Type	Description
vector	FLOAT	Matrix elements as vector in row-major order

Sample

local vector = Matrix.toVector(matrix)

transpose()

Short description

Returns the transposed matrix.

Parameters
Name	Type	Description
matrix	CONST_OBJECT Matrix	The instance to use

Return values
Name	Type	Description
transposedMatrix	OBJECT Matrix	The transposed matrix.

Sample

local transposedMatrix = Matrix.transpose(matrix)

Mesh

Short description

Object for a 3D surface represented by a triangle mesh. The mesh consists of a vector of vertices (3D points) and vector of triplets defining the 3 vertex indices of each triangle. For each vertex, there can also be a 3D normal and an intensity or RGBA color component. There are two types of triangle representations indexed triangles or separated triangles. In the case of indexed triangles a vertex can be used by several triangles, and in the case of separated triangles a vertex can only be used by a single triangle. In some cases a combination of both representations is also possible. Unless known it might be unclear what representation the mesh has. The representation has consequences in how algorithms perform; an example is the connected components algorithm, with separated triangles none of the triangles share vertex indices so only single connections (1 triangle) can be found. In this case a search radius must be specified to search for nearby vertices.

Overview

clone(), create(), getTriangleCount(), getVertexCount(), hasColor(), hasIntensity(), hasNormals(), hasTextureCoordinates(), load(), save(), toString()

Functions

clone()

Short description

Returns a duplicated instance of the input mesh. This is a full copy and might be very slow dependent on the mesh size.

Parameters
Name	Type	Description
inputMesh	CONST_OBJECT Mesh	The mesh to clone.

Return values
Name	Type	Description
clone	OBJECT Mesh	The new cloned mesh object.

Sample

local clone = Mesh.clone(inputMesh)

create()

Short description

Creates a new empty mesh object

Return values
Name	Type	Description
newMesh	OBJECT Mesh	The newly created mesh

Sample

local newMesh = Mesh.create()

getTriangleCount()

Short description

Returns the number of triangles in the mesh.

See also

Mesh.getVertexCount

Parameters
Name	Type	Description
mesh	CONST_OBJECT Mesh	The mesh.

Return values
Name	Type	Description
triangleCount	INT	The mesh number of triangles.

Sample

local triangleCount = Mesh.getTriangleCount(mesh)

getVertexCount()

Short description

Returns the number of vertices in the mesh.

See also

Mesh.getTriangleCount

Parameters
Name	Type	Description
mesh	CONST_OBJECT Mesh	The mesh.

Return values
Name	Type	Description
vertexCount	INT	The mesh number of vertices.

Sample

local vertexCount = Mesh.getVertexCount(mesh)

hasColor()

Short description

Check if the mesh contains colors.

Parameters
Name	Type	Description
mesh	CONST_OBJECT Mesh	The mesh.

Return values
Name	Type	Description
foundColor	BOOL	True if the mesh contains colors.

Sample

local foundColor = Mesh.hasColor(mesh)

hasIntensity()

Short description

Check if the mesh contains intensities.

Parameters
Name	Type	Description
mesh	CONST_OBJECT Mesh	The mesh.

Return values
Name	Type	Description
foundIntensity	BOOL	True if the mesh contains intensities.

Sample

local foundIntensity = Mesh.hasIntensity(mesh)

hasNormals()

Short description

Check if the mesh contains normals.

Parameters
Name	Type	Description
mesh	CONST_OBJECT Mesh	The mesh.

Return values
Name	Type	Description
foundNormals	BOOL	True if the mesh contains normals.

Sample

local foundNormals = Mesh.hasNormals(mesh)

hasTextureCoordinates()

Short description

Check if the mesh contains texture coordinates.

Parameters
Name	Type	Description
mesh	CONST_OBJECT Mesh	The mesh.

Return values
Name	Type	Description
foundTextureCoordinates	BOOL	True if the mesh contains texture coordinates.

Sample

local foundTextureCoordinates = Mesh.hasTextureCoordinates(mesh)

load()

Short description

Loads a mesh from the specified file path. The format is defined by the file extension: .ply: Polygon File Format .json: JSON .msgpack: MessagePack

See also

Parameters
Name	Type	Description
filePath	STRING	The path and name of the file to load the mesh from.

Return values
Name	Type	Description
mesh	OBJECT Mesh	The mesh object.

Sample

mesh = Mesh.load("private/mesh.ply")

save()

Short description

Saves a mesh to the specified file path. Overwrites the file if it already exists. The format is defined by the file extension: .ply: Polygon File Format (Optional useBinary parameter is supported). .json: JSON (Optional useBinary parameter not supported). .msgpack: MessagePack (Optional useBinary parameter not supported).

See also

create(), getMemoryUsage(), getPrivateDataUsage(), getStatusInfo()

Parameters
Name	Type	Description
mesh	CONST_OBJECT Mesh	The Mesh object which is saved.
filepath	STRING	The path and name of the file to save the mesh to.
useBinary	BOOL	Optional parameter that can only be used when saving to .ply format. If true write the ply data (except the header) in binary instead of ASCII. Default is true.

Return values
Name	Type	Description
success	BOOL	Returns true if the mesh has been successfully saved.

Sample

local success = Mesh.save(mesh, "private/mesh.ply", useBinary)

toString()

Short description

Gets a user-friendly string description of the mesh, containing important properties.

Parameters
Name	Type	Description
mesh	CONST_OBJECT Mesh	The mesh to describe.

Return values
Name	Type	Description
str	STRING	User-friendly description of the mesh.

Sample

str = Mesh.toString(mesh)

Monitor

Short description

Provides monitoring functionality

Monitor.App

Short description

Provides monitoring access to the status info of an app like app status and memory usage.

Overview

Functions

create()

Short description

Creates a new instance.

Parameters
Name	Type	Description
appName	STRING	The name of the app to monitor.

Return values
Name	Type	Description
handle	HANDLE	handle to the App-monitor.

Sample

handle = Monitor.App.create("HelloWorld")

getMemoryUsage()

Short description

Get the script interpreter memory usage of the app.

Parameters
Name	Type	Description
monitorHandle	HANDLE	Handle to the App-monitor.

Return values
Name	Type	Description
usedBytes	INT	Memory-bytes used by the script interpreter of this app.

Sample

Monitor.App.getMemoryUsage(handle)

getPrivateDataUsage()

Short description

Get the AppData usage of the app.

Parameters
Name	Type	Description
monitorHandle	HANDLE	Handle to the App-monitor.

Return values
Name	Type	Description
usedBytes	INT	Bytes in the AppData folder used by this app.
capacityBytes	INT	Total capacity of the AppData folder for all apps in bytes.
appDataUsage	FLOAT	The used bytes of the app in percent of the whole capactiy of the AppData folder.

Sample

Monitor.App.getPrivateDataUsage(handle)

getStatusInfo()

Short description

Get the status of the app.

Parameters
Name	Type	Description
monitorHandle	HANDLE	Handle to the App-monitor.

Return values
Name	Type	Description
state	ENUM AppStatus	Status of the app.
additionalInfo	STRING	Additional info to the status of the App. This can be the crash reason in case of a crash.

Sample

Monitor.App.getStatusInfo(handle)

Monitor.CPU

Short description

Provides monitoring access to CPU load in sum and for each core.

Overview

create(), getLoad()

Functions

create()

Short description

Creates a new instance. Can be instantiated multiple times.

Return values
Name	Type	Description
handle	HANDLE	handle to the CPU-monitor.

Sample

handle = Monitor.CPU.create()

getLoad()

Short description

Get the current load of the CPU.

Parameters
Name	Type	Description
monitorHandle	HANDLE	Handle to the CPU-monitor.

Return values
Name	Type	Description
overallLoad	FLOAT	The overall CPU load in percent.
detailedLoad	FLOAT	The load of each CPU core in percent.

Sample

Monitor.CPU.getLoad(handle)

Monitor.Memory

Short description

Provides monitoring access to the RAM memory usage of the device.

Overview

create(), getUsage()

Functions

create()

Short description

Creates a new instance.

Return values
Name	Type	Description
handle	HANDLE	handle to the Memory-monitor.

Sample

handle = Monitor.Memory.create()

getUsage()

Short description

Get the current memory usage.

Parameters
Name	Type	Description
monitorHandle	HANDLE	Handle to the Memory-monitor.

Return values
Name	Type	Description
usedBytes	INT	Currently used bytes.
capacityBytes	INT	Memory capacity in bytes.
memUsage	FLOAT	The memory used in percent of the whole capacity.

Sample

Monitor.Memory.getUsage(handle)

Monitor.Network

Short description

Provides monitoring access to the network interface load of each interface or all interfaces together.

Overview

create(), getLoad()

Functions

create()

Short description

Creates a new instance.

Parameters
Name	Type	Description
interface	ENUM EthernetInterfaces	The interface to monitor. Use 'ALL' to monitor all interfaces.

Return values
Name	Type	Description
handle	HANDLE	Handle to the Network-monitor. Will return nil if the interface is not valid, or if no statistics can be loaded.

Sample

Monitor.Network.create("ETH1")

getLoad()

Short description

Get the current network load.

Parameters
Name	Type	Description
monitorHandle	HANDLE	Handle to the Network-monitor.

Return values
Name	Type	Description
sentBytesPerSec	INT	Current bytes sent per second.
receivedBytesPerSec	INT	Current bytes received per second.

Sample

Monitor.Network.getLoad(handle)

NTPClient

Short description

Offers access to control the NPTClient of the device. There can be only one NPTClient running on one defined ethernet interface. Also there can be only one controlling the NTPClient, therefore the handle can only be instantiated once. If the handle is destructed, the last NTP configuration keeps active and NTPClient stays running if activated.

Overview

create(), setApplyEnabled(), setInterface(), setPeriodicUpdateEnabled(), setServerAddress(), setServerPort(), setTimeSource(), setTimeout(), startManualRequest()

Functions

create()

Short description

Creates a handle to the NTPClient. Only one instance can be acquired.

Return values
Name	Type	Description
handle	HANDLE	Unique handle for the NTPClient. nil if there is already another instance or if the device has no NTP functionality.

Sample

handle = NTPClient.create()

setApplyEnabled()

Short description

Enables or disables the application of the timestamp received by NTP to the system time.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the NTPClient object.
state	BOOL	Set to true to apply NTP time to system time. If set to false the NTP time is just printed to the log.

Sample

NTPClient.setApplyEnabled(handle, false)

setInterface()

Short description

Sets the interface to use for connecting.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the NTPClient object.
ifName	ENUM EthernetInterfaces	One of the available interfaces

Sample

NTPClient.setInterface(handle, "ETH1")

setPeriodicUpdateEnabled()

Short description

Enables or disables periodic NTP requests. Per default, the periodic update is enabled if time source is set to 'NTP'.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the NTPClient object.
state	BOOL	Set to true to request time updates from NTP in 10 minute intervals. If set to false you must trigger requests manually by using startManualRequest().

Sample

NTPClient.setPeriodicUpdateEnabled(handle, true)

setServerAddress()

Short description

Sets the NTP server address.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the NTPClient object.
address	STRING	Address of the NTP server.

Sample

NTPClient.setServerAddress(handle, "192.168.0.1")

setServerPort()

Short description

Sets the NTP server port.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the NTPClient object.
port	INT	Port of the NTP server.

Sample

NTPClient.setServerPort(handle, 12345)

setTimeSource()

Short description

Configures the source of the system time.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the NTPClient object.
source	ENUM TimeSource	System time source.

Return values
Name	Type	Description
success	BOOL	True if successfully set, false if not.

Sample

success = NTPClient.setTimeSource(handle, "MANUAL")

setTimeout()

Short description

Sets the timeout for NTP requests in milliseconds.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the NTPClient object.
timeout	INT	Timeout in milliseconds.

Sample

NTPClient.setTimeout(handle, 5000)

startManualRequest()

Short description

Trigger a NTP request manually now. TimeSource needs to be set to 'NTP' so that this function works, otherwise returns false. This function does not block until the request is over, it just triggers an asynchronous start of a request.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the NTPClient object.

Return values
Name	Type	Description
success	BOOL	True if request was successfully triggered, false if not possible because not configured to NTP or internal error.

Sample

success = NTPClient.startManualRequest(handle)

OPCUA

Short description

Provides OPC UA server functionality. OPC UA Overview: The OPC Unified Architecture (UA), released in 2008, is a platform independent service-oriented architecture that integrates all the functionality of the individual OPC Classic specifications into one extensible framework. It is developed by the OPC Foundation. See reference document 1 for more details about the protocol. API Overview: This API implements all the functions that are required to start a OPC UA server. It allows to create nodes of different classes, e.g. variables, objects or methods, and connect them via references to build up a custom information model. Nodes are grouped together into a namespace. A server can have one or more namespaces. The provided functions can be categorized into three groups: 1. Server management and server configuration: OPCUA.Server.* 2. Creating and managing namespaces: OPCUA.Server.Namespace.* 3. Creating, managing and using nodes and references: OPCUA.Server.Node.* According to internal, unofficial tests, this OPC UA CROWN can be used to fulfill the following OPC UA Profiles: - Nano Embedded Device Server Profile (Compliance Test Tool version 1.3.340.380) - SecurityPolicy - None (requires openSSL library) - SecurityPolicy - Basic128Rsa15 (requires openSSL library) - SecurityPolicy - Basic256 (requires openSSL library) - SecurityPolicy - Basic256Sha256 (requires openSSL library) So far, no other profiles are fulfilled. Please note that profile compliance was tested with a reference server implementation using this OPC UA CROWN. Other server implementations using this CROWN need to be tested separately according to the official OPC UA certification procedure in order to officially claim compliance. The server allows the following user token policies: - anonymous - user name / password So far, no other user token policies (e.g., x509, token, …) are supported. Limitations: - The server does not fulfill the other OPC UA Profiles for servers: Micro Embedded Device Server, Embedded UA Server and Standard UA Server. - loading of NodeSet2 files supported only if server supports the objects and value in the file (e.g., it does not support loading of 2-dimensional values) - If a target device platform does not provide openSSL library, then all security features are disabled. - Only one transport type is supported: UA TCP - UA Secure Conversation - UA Binary. - It is possible to use custom structured data types, however these types must be loaded from XML files. Access to these data types can be done through Value CROWN. - Only one-dimensional arrays are supported. - Unsupported service sets: — NodeManagement Service Set: AddNodes, AddReferences, DeleteNodes, DeleteReferences — View Service Set: RegisterNodes, UnregisterNodes, Query Service Set, QueryFirst, QueryNext — Attribute Service Set: HistoryRead, HistoryUpdate - Unsupported built-in data types: — XmlElement — ExtensionObject (but enumerations are supported) — DataValue — Variant — nested DiagnosticInfos Reference Documents: 1. OPC Unified Architecture Specification, Parts 1-13, https://opcfoundation.org/developer-tools/specifications-unified-architecture

OPCUA.Server

Short description

Provides OPC UA Server functionality.

Overview

create(), getNamespace(), loadNodeSet2File(), resetAddressSpace(), setApplicationName(), setApplicationURI(), setConfiguration(), setInterface(), setNamespaces(), setPort(), start(), stop()

Functions

create()

Short description

Create a new OPC UA Server instance. Server address space is in a default state (i.e., a pristine NS0). Network communication is not active.

Return values
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Server. Currently, it is only possible to create a single instance handle. Fails with return value nil when another instance handle already exists.

Sample

handle = OPCUA.Server.create()

getNamespace()

Short description

Retrieve a namespace from the server

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Server
index	INT	The index of the namespace to get.

Return values
Name	Type	Description
namespace	OBJECT OPCUA.Server.Namespace	The requested namespace or nil if the namespace can not be found

loadNodeSet2File()

Short description

Load a NodeSet2 XML file. This method can be called multiple times to load different files. In case of an error during loading (e.g, due to invalid file contents), loading stops when the error is encountered. Consider using resetAddressSpace() to remove partially loaded files from address space.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Server
fileName	STRING	NodeSet2 XML file to load

Return values
Name	Type	Description
status	BOOL	True if loaded successfully, false otherwise

resetAddressSpace()

Short description

Reset the OPC UA server. Whole address space is reset to default state (i.e., a pristine NS0). All CROWN instances to existing nodes become invalid. Other settings (e.g., network settings) are not affected by reset. Call reset() only when server is stopped.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Server

Return values
Name	Type	Description
success	BOOL	Is true when the OPC UA server has been reset successfully, false if an error occurred.

Sample

success = OPCUA.Server.resetAddressSpace(handle)

setApplicationName()

Short description

Set the name of the application. This name is shown to clients as the name of the server and should describe what the server actually does.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Server
name	STRING	Name of the application that is shown to clients

Sample

OPCUA.Server.setApplicationName(handle, "MyApplication")

setApplicationURI()

Short description

Set the Application URI. Call to this function is optional. The Application URI of a server represents a globally-unique logical name for a Server within the scope of the network in which it is installed. This identifier should be a fully qualified domain name; however, it may be a GUID or similar construct that ensures global uniqueness. If this function is not called, the following default ApplicationURI urn://sick.com/opc/ua/serial/${DEVICE_PRODUCT}/${SERIAL_NUMBER} is used, where the variable ${DEVICE_PRODUCT} is replaced by the device name and ${SERIAL_NUMBER} is replaced by the serial number. Example for a SIM4000 device: urn://sick.com/opc/ua/serial/SIM4000/12345678

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Server
uri	STRING	Application URI. Can be chosen freely, but SICK recommends to use the following format: urn://sick.com/opc/ua/app/[product/]unique_identifier. The unique_identifier should not change on device reset.

Sample

OPCUA.Server.setApplicationURI(handle, "urn://sick.com/opc/ua/app/sim/sim4000/my_application_uid")

setConfiguration()

Short description

Set a ServerConfiguration. Please note that server copies the configuration when this function is called.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Server
config	OBJECT OPCUA.Server.ServerConfiguration	The configuration for the OPC UA Server

setInterface()

Short description

Set the interface on which the server should listen. Call to this function is optional. By default, server listens all interfaces. On multi-homed hosts, it is recommended to bind the server to one specific interface. Otherwise, one OPC UA EndPoint is created for each IP address and the client has to select the right one manually. This function will become deprecated soon. See description of OPCUA CROWN for more details.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Server
ifName	ENUM EthernetInterfaces	One of the available interfaces

Sample

OPCUA.Server.setInterface(handle, "ETH1")

setNamespaces()

Short description

Set all OPC UA Namespaces the server should use. Please note that his removes any nodes that are neither in standard namespace NS0 nor in the namespaces parameter.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Server
namespaces	OBJECT OPCUA.Server.Namespace	The Namespace objects the server should use. All Namespaces which have been added previously are removed.

Sample

OPCUA.Server.setNamespaces(handle, {namespace1, namespace2})

setPort()

Short description

Set the port on which the server should listen. Call to this function is optional. By default, port is 4840. This function will become deprecated soon. See description of OPCUA CROWN for more details.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Server
port	INT	The server port between 1 and 65535.

Sample

OPCUA.Server.setPort(handle, 4840)

start()

Short description

Start the network communication. After a successful start, OPC UA clients can connect to server via network.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Server

Return values
Name	Type	Description
success	BOOL	Is true when the OPC UA server has been started successfully, false if an error occurred.

Sample

success = OPCUA.Server.start(handle)

stop()

Short description

Stop the OPC UA server’s network communication.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Server

Return values
Name	Type	Description
success	BOOL	Is true when the OPC UA server has been stopped successfully, false if an error occurred.

Sample

OPCUA.Server.stop(handle)

OPCUA.Server.EndpointConfiguration

Short description

An EndpointConfiguration consists of (1) a certificate store configuration, (2) a non-empty set of SecurityConfigurations, (3) a boolean flag for enabling application authentication, (4) a reference to an UserTokenDatabase and (5) a bind URL.

Overview

create(), enableApplicationAuthentication(), setCertificateStoreConfiguration(), setInterface(), setPort(), setSecurityConfigurations(), setUserTokenDatabase()

Functions

create()

Short description

Create an EndpointConfiguration with default values. Default values are: (1) no certificate store, (2) one SecurityConfiguration with default values, (3) application authentication = disabled, (4) empty UserTokenDatabase (5) interface ="ALL" and (6) port = 4840.

Return values
Name	Type	Description
config	OBJECT OPCUA.Server.EndpointConfiguration	Configuration with default values

Sample

obj = OPCUA.EndpointConfiguration.create()

enableApplicationAuthentication()

Short description

Enable or disable application authentication.

Parameters
Name	Type	Description
config	OBJECT OPCUA.Server.EndpointConfiguration	The configuration whose application authentication should be enabled / disabled.
enabled	BOOL	Set to true to enable application authentication.

setCertificateStoreConfiguration()

Short description

Sets the CertificateStoreConfiguration.

Parameters
Name	Type	Description
config	OBJECT OPCUA.Server.EndpointConfiguration	The configuration whose CertificateStoreConfiguration should be set.
certificateStoreConfiguration	OBJECT [API:DataFormat:]	The CertificateStoreConfiguration to set. Pass nil to indicate that no certificate store should be used.

setInterface()

Short description

Sets the interface to bind the Endpoint to. If interface is set to "ALL", then the Endpoint binds to all network interfaces. In such a case there can only be one EndpointConfiguration in a ServerConfiguration.

Parameters
Name	Type	Description
config	OBJECT OPCUA.Server.EndpointConfiguration	The configuration whose bind URL should be set.
interface	ENUM EthernetInterfaces	The interface to bind to (e.g., ETH1).

setPort()

Short description

Sets the port to listen to.

Parameters
Name	Type	Description
config	OBJECT OPCUA.Server.EndpointConfiguration	The configuration whose bind URL should be set.
port	INT	The server port between 1 and 65535.

setSecurityConfigurations()

Short description

Sets the SecurityConfigurations.

Parameters
Name	Type	Description
config	OBJECT OPCUA.Server.EndpointConfiguration	The configuration whose SecurityConfigurations should be set.
securityConfigurations	OBJECT OPCUA.Server.SecurityConfiguration	Non-empty set of security configurations.

setUserTokenDatabase()

Short description

Sets the UserTokenDatabase. Please note that the behavior of this setter only stores a reference to the UserTokenDatabase. This allows the sharing of one UserTokenDatabase among multiple EndPoints. Consequences are: (1) if a server S is configured to use a UserTokenDatabase instance U and U.addUserPassword("x", "y") is called, then S immediately accepts the user x.

Parameters
Name	Type	Description
config	OBJECT OPCUA.Server.EndpointConfiguration	The configuration whose UserTokenDatabase should be set.
userTokenDatabase	OBJECT OPCUA.Server.UserTokenDatabase	The UserTokenDatabase to set. Pass nil to indicate that no UserTokenDatabase should be used.

OPCUA.Server.FileCertificateStoreConfiguration

Short description

FileCertificateStoreConfiguration contains information about a file-based certificate store. The only parameter of this certificate store type is the root directory. All other directories should be created with fixed names below root directory. Directory layout: - ${rootDir}/issuer/certs: The issuer directory contains non-trusted issuer / certificate authority (CA) certificates - ${rootDir}/issuer/crl: The issuer CRL directory contains the CRLs of the CA certs from issuer directory. - ${rootDir}/trusted/certs: The trusted directory contains trusted CA certificates and self-signed certificates. - ${rootDir}/trusted/crl: The trusted CRL directory contains the CRLs of the CA certs from trusted directory. Please note that FileCertificateStoreConfiguration only holds the information where to look for certificates. The app developer is responsible for ensuring that the directories exist and contain the required files.

Overview

create(), setRootDirectory()

Functions

create()

Short description

Creates a file store configuration with root directory = "."

Return values
Name	Type	Description
config	OBJECT OPCUA.Server.FileCertificateStoreConfiguration	The created FileCertificateStoreConfiguration instance.

Sample

obj = OPCUA.FileCertificateStoreConfiguration.create()

setRootDirectory()

Short description

Sets the root directory.

Parameters
Name	Type	Description
database	OBJECT OPCUA.Server.FileCertificateStoreConfiguration	The configuration whose root directory should be set.
rootDir	STRING	The root directory.

OPCUA.Server.Namespace

Short description

Represents a OPC UA namespace. A OPC UA Server can work with one or more user defined namespaces. Namespaces can be added to the server using the function OPCUA.Server.setNamespaces.

Overview

create(), getNode(), getNodeFromStandardNamespace(), setIndex(), setNodes(), setRootNode()

Functions

create()

Short description

Create a new OPC UA Namespace instance.

Return values
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Namespace

Sample

handle = OPCUA.Server.Namespace.create()

getNode()

Short description

Retrieve an OPC UA node that is inside the namespace.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Namespace
idType	ENUM NodeIDType	Type of the ID
id	AUTO	The ID of the Node to get

Return values
Name	Type	Description
node	OBJECT OPCUA.Server.Node	The requested node or nil if the node can not be found

Sample

local node = OPCUA.Server.Namespace.getNode(handle, "STRING", "MySimpleVariableNode")

getNodeFromStandardNamespace()

Short description

Retrieve a node that is part of the standard namespace NS0. The available Node IDs are listed in the OPC Unified Architecture Specification, Part 6: Mappings, Annex B: OPC UA Nodeset.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Namespace
idType	ENUM NodeIDType	Type of the ID
id	AUTO	The ID of the Node to get

Return values
Name	Type	Description
node	OBJECT OPCUA.Server.Node	The requested node or nil if the node can not be found

Sample

local node = OPCUA.Server.Namespace.getNodeFromStandardNamespace(handle, "NUMERIC", 5)

setIndex()

Short description

Sets the index of the namespace. Calling this function. By default, namespace indices are assigned automatically in the order of namespace creation, starting with index 2.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Namespace
index	INT	The namespace index to use. Must not be in use by any other namespace.
url	STRING	URL that identifies the namespace, is shown to clients for a better understanding of the namespace index. Should start with urn://. If not provided, default is device_product/namespace_index_as_string

Sample

OPCUA.Server.Namespace.setIndex(handle, 3)

setNodes()

Short description

Set all nodes that belong to this namespace.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Namespace
nodes	OBJECT OPCUA.Server.Node	All nodes that should belong to this namespace, including the root node.

Sample

OPCUA.Server.Namespace.setNodes(handle, {node1, node2})

setRootNode()

Short description

Sets the root node of the namespace.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Namespace
root	OBJECT OPCUA.Server.Node	The root node. It is recommended to use a folder node as root
suspensionFolder	OBJECT OPCUA.Server.Node	Optional. The node (folder) that is the parent node of root. Default is the global root node of the OPC UA default namespace

Sample

OPCUA.Server.Namespace.setRootNode(handle, rootNode)

OPCUA.Server.Node

Short description

Represents a single node in the address space of a OPC UA server. Some node types (of type "Variable" and "VariableType") contain values. These can be accessed via getValue(), setValue() and getValueHandle(). For more information on value handling see OPCUA.Server.Value CROWN.

Functions

addReference()

Short description

Create a reference from this node to another node. An inverse reference from the target node to this node is created automatically, if possible. Example: When creating a reference from folderNode to otherNode with reference type "Organizes", otherNode automatically gets an inverse reference of type "OrganizedBy" to folderNode.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Node
type	ENUM ReferenceType	Type of the reference between this node and the target node
other	OBJECT OPCUA.Server.Node	The target node to which the reference points

Sample

OPCUA.Server.Node.addReference(folderHandle, "ORGANIZES", simpleVariable)

callMethod()

Short description

Call the method on the node

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Node
parameters	OBJECT OPCUA.Server.Value	The parameters that should be used for the call. Might be omitted (nil) if there are no parameters.

Return values
Name	Type	Description
returnValues	OBJECT OPCUA.Server.Value	The return values of the call. Might be omitted (nil) if there are no return values.

Sample

OPCUA.Server.Node.callMethod(handle, {paramValueHandle1, paramValueHandle2}) -- This method takes two parameters

create()

Short description

Creates a new OPC UA node.

Parameters
Name	Type	Description
class	ENUM NodeClass	Class of the node

Return values
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Node

Sample

handle = OPCUA.Server.Node.create("VARIABLE")

createEventParameters()

Short description

Create the parameters for an event; only works for event type nodes

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Node

Return values
Name	Type	Description
parameters	OBJECT OPCUA.Server.Value	The parameters of the call. Might be omitted (nil) if there are no parameters.

Sample

OPCUA.Server.Node.createEventParameters(handle)

createMethodParameters()

Short description

Create the default parameters for a method

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Node

Return values
Name	Type	Description
parameters	OBJECT OPCUA.Server.Value	The return values of the call. Might be omitted (nil) if there are no return values.

Sample

OPCUA.Server.Node.createMethodParameters(handle)

deregister()

Short description

This function is used to deregister from any registered event of the handle.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
eventname	STRING	The event to deregister from
callback	STRING	The function name which was registered on the event

Return values
Name	Type	Description
success	BOOL	True if successfully deregistered. False if event does not exist or callback wasn’t registered.

getValue()

Short description

Gets the current value of the OPC UA node. Only works if NodeClass is VARIABLE or OBJECT.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Node

Return values
Name	Type	Description
value	AUTO	The value of the node

Sample

local value = OPCUA.Server.Node.getValue(handle)

getValueHandle()

Short description

Gets the current value (a handle for the value) of the OPC UA node. Only works if NodeClass is VARIABLE or VARIABLE_TYPE.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Node

Return values
Name	Type	Description
value	HANDLE	The value of the node

Sample

local value = OPCUA.Server.Node.getValueHandle(handle)

notifyEvent()

Short description

Let the node notify the given event if it is a source of this event. (All Notifier nodes are informed)

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Node
fireEventType	OBJECT OPCUA.Server.Node	Type of the event to be notified (instance of EventType (ObjectType))
severity	ENUM EventSeverity	How severe is the event to be notified
message	STRING	Message to be transferred (human readable)
parameters	OBJECT OPCUA.Server.Node	The additional parameters of the event

Sample

OPCUA.Server.Node.notifyEvent(handle, eventTypeNode, "MEDIUM", "demoEvent occurred.")

register()

Short description

This function is used to register for any event of the handle.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
eventname	STRING	The event to register to
callback	STRING	The function name to call on the event occurrence

Return values
Name	Type	Description
success	BOOL	True if successfully registered. False if event does not exist.

registerCallbacks()

Short description

Register functions that should be called to get or set the value of the OPC UA node. The getter function has the following signature: no input parameters. Getter returns a value of type OPCUA.Server.Value. For legacy compatibility it is still possible to return builtin values. It is strongly recommended to return OPCUA.Server.Value, because legacy behaviour is deprecated and will be removed soon. The setter function has the following signature: one OPCUA.Server.Value value as input parameter. Setter returns true if value was set successful, false otherwise. Please note that OPCUA.Server.Value is used to enable setting of complex types (e.g., structures or unions). There is not guarantee on the number of getter/setter callback invocations by internal mechanism. In general, lua callbacks should not be used for runtime performace crtical features.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Node
getter	STRING	Name of the Getter function
setter	STRING	Name of the Setter function. The function must return a bool value that indicates success (true) or failure (false)

Sample

OPCUA.Server.Node.registerCallbacks(handle, getter, setter)

setAccessLevel()

Short description

Function to set access level to values of VARIABLE nodes.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Node
accessLevel	ENUM AccessLevel	Access level for the variable

Sample

OPCUA.Server.Node.setAccessLevel(handle, "READ_WRITE")

setArrayDimensions()

Short description

Specify the size of an array. For each dimension of the array, a corresponding value in the list specifies the length of the dimension. Currently, only one-dimensional arrays are supported. A data type must be set before setting the dimensions.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Node
dimensions	INT	The dimensions with specified length. If the first dimension is zero, scalar value is used.

Sample

OPCUA.Server.Node.setArrayDimensions(handle, {3})

setBrowseName()

Short description

Sets the name of the node that is used for browsing.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Node
browseName	STRING	The browse name to use

Sample

OPCUA.Server.Node.setBrowseName(handle, "MySimpleVariableNode")

setDataType()

Short description

Set the data type of the OPC UA node to one of the standard node types. Arbitrary types can be set by using the function setDataTypeByNode instead. Only applies to nodes of type VARIABLE or VARIABLE_TYPE.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Node
type	ENUM DataType	The type of this node

Sample

OPCUA.Server.Node.setDataType(handle, "UINT32")

setDataTypeByNode()

Short description

Set the type of the OPC UA node. For standard node types use the function setDataType instead. Only applies to nodes of type VARIABLE or VARIABLE_TYPE.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Node
type	OBJECT OPCUA.Server.Node	The OPC UA Node which represents the type

Sample

OPCUA.Server.Node.setDataTypeByNode(handle, typeNode)

setDescription()

Short description

Sets the description (explaining text) of the node. Optional. If not called, BrowseName is used.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Node
description	STRING	The description text

Sample

OPCUA.Server.Node.setDescription(handle, "Description of this node.")

setDisplayName()

Short description

Sets the name of the node that is used for displaying at clients. Optional. If not called, BrowseName is used.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Node
displayName	STRING	The display name to use

Sample

OPCUA.Server.Node.setDisplayName(handle, "MySimpleVariableNode")

setEnumChoices()

Short description

Function to an enum choice to a DATA_TYPE node. Will make the node automatically sub node of Enumeration type (i=29). The same name must not be given multiple times.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Node
value	STRING	Name of the choice to add

Sample

OPCUA.Server.Node.setEnumChoices(handle, {"NAME OF THE CHOICE", "NAME OF CHOICE 2"})

setID()

Short description

Sets the ID of the OPC UA node.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Node
type	ENUM NodeIDType	Which type of ID to use
id	AUTO	The ID. Must be unique within a namespace

Sample

OPCUA.Server.Node.setID(handle, "STRING", "MySimpleVariableNode")

setMethodBehavior()

Short description

This function is used to register a callback that is executed when a client calls the method. Optionally, it is possible to set one or more return values and parameters for the method.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Node
callback	STRING	Function name to call when client calls the method. Is optional, a callback is not needed if this METHOD node is part of an OBJECT_TYPE.
returnValues	ENUM DataType	Specifies number and data type of the method return values
parameters	ENUM DataType	Specifies number and data type of method parameters

Sample

OPCUA.Server.Node.setMethodBehavior(handle, "callbackFunctionName", {"BOOL"}, {"INT32"}) -- This method takes one INT32 as argument and returns BOOL

setTypeDefinition()

Short description

Set the type of the OPC UA node to one of the standard node types. Arbitrary types can be set by using the function setTypeDefinitionByNode instead.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Node
type	ENUM NodeType	The type of this node

Sample

OPCUA.Server.Node.setTypeDefinition(handle, "FOLDER_TYPE")

setTypeDefinitionByNode()

Short description

Set the type of the OPC UA node. For standard node types, the function setTypeDefinition can be used instead.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Node
type	OBJECT OPCUA.Server.Node	The OPC UA Node which represents the type

Sample

OPCUA.Server.Node.setTypeDefinitionByNode(handle, typeNode)

setValue()

Short description

Sets the current value of the OPC UA node. Only works if NodeClass is VARIABLE or OBJECT.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Node
value	AUTO	The new value for the node

Sample

OPCUA.Server.Node.setValue(handle, 123)

Events

OnWrite

Short description

This event is thrown when a Node of type VARIABLE is written by a OPC UA client. It is not thrown when a Node is written internally via API function OPCUA.Server.Node.setValue(). If the write does not change the value, the event is thrown anyway.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Node

OPCUA.Server.SecurityConfiguration

Short description

A security configuration consists of (1) a set of credentials (a certificate and a private key representing the server), (2) a SecurityPolicy, (3) a set of MessageSecurityModes and (4) a set of UserTokenPolicies. Each endpoint has one or more SecurityConfigurations.

Overview

create(), setMessageSecurityModes(), setSecurityPolicy(), setServerCredentials(), setUserTokenPolicies()

Functions

create()

Short description

Creates a SecurityConfiguration with default settings. Default settings are: (1) UserTokenPolicy = ANONYMOUS, (2) MessageSecurityMode = NONE, (3) no server credentials and (4) SecurityPolicy = NONE

Return values
Name	Type	Description
config	OBJECT OPCUA.Server.SecurityConfiguration	Default SecurityConfiguration instance

Sample

handle = OPCUA.Server.SecurityConfiguration.create()

setMessageSecurityModes()

Short description

Sets a set of MessageSecurityModes.

Parameters
Name	Type	Description
config	OBJECT OPCUA.Server.SecurityConfiguration	The configuration instance whose MessageSecurityModes should be set
modes	ENUM MessageSecurityMode	Non-empty, duplicate-free list of MessageSecurityModes

setSecurityPolicy()

Short description

Sets the security policy

Parameters
Name	Type	Description
config	OBJECT OPCUA.Server.SecurityConfiguration	The configuration instance whose SecurityPolicy should be set
securityPolicy	ENUM SecurityPolicy	The SecurityPolicy to use

setServerCredentials()

Short description

Sets the server credentials. The certificate and the private key have to match. Either specify both or none. Specify none in case that no server credentials should be used (i.e., no signing and/or encryption is used). Parameters certificate and privateKey are interpreted in the context of the used certificate store. When used together with a FileCertificateStoreConfiguration, certificate and privateKey parameters are interpreted as files. However, future releases might introduce different types of key stores (e.g., remote certificate stores or hardware key stores). In that case, parameters certificate and privateKey specify something different than file names.

Parameters
Name	Type	Description
config	OBJECT OPCUA.Server.SecurityConfiguration	The configuration instance whose server credentials should be set
certificate	STRING	When using FileCertificateStoreConfiguration, this parameter specifies the name of the file where the certificate to be used for the server is stored in DER format. Use empty string ("") if no certificate shall be used.
privateKey	STRING	When using FileCertificateStoreConfiguration, this parameter specifies the name of the file where the private key to be used for the server is stored in PEM format. Use empty string ("") if no private key shall be used.

setUserTokenPolicies()

Short description

Sets a set of UserTokenPolicies.

Parameters
Name	Type	Description
config	OBJECT OPCUA.Server.SecurityConfiguration	The configuration instance whose UserTokenPolicies should be set
policies	ENUM UserTokenPolicy	Non-empty, duplicate-free list of UserTokenPolicies

OPCUA.Server.ServerConfiguration

Short description

Configuration of an OPC UA server. Default server configuration has (1) a list with one EndpointConfiguration set to default values.

Overview

create(), setEndpointConfigurations()

Functions

create()

Short description

Creates a server configuration with default parameters.

Return values
Name	Type	Description
config	OBJECT OPCUA.Server.ServerConfiguration	The created configuration.

Sample

obj = OPCUA.Server.ServerConfiguration.create()

setEndpointConfigurations()

Short description

Sets the endpoint configurations.

Parameters
Name	Type	Description
config	OBJECT OPCUA.Server.ServerConfiguration	The ServerConfigration whose EndpointConfigurations should be set.
endpointConfigurations	OBJECT OPCUA.Server.EndpointConfiguration	Non-empty list of EndpointConfigurations.

OPCUA.Server.UserTokenDatabase

Short description

UserTokenDatabase is used for maintaining a set of user credentials that can be used to authenticate at an OPC UA Endpoint. UserTokenDatabases are set to EndpointConfigurations in a reference-like manner. This was done to allow several endpoints to use the same UserTokenDatabase. When endpoints are created from a ServerConfiguration, server starts to uses the references UserTokenDatabase(s). As consequences, any changes to a user database apply directly to the (running) server.

Overview

addUserPassword(), create()

Functions

addUserPassword()

Short description

Add a user with a password to the database.

Parameters
Name	Type	Description
database	OBJECT OPCUA.Server.UserTokenDatabase	The database to add the user to.
userName	STRING	Name of the user.
password	STRING	Password of the user

create()

Short description

Creates an empty database.

Return values
Name	Type	Description
database	OBJECT OPCUA.Server.UserTokenDatabase	The created database.

Sample

obj = OPCUA.UserTokenDatabase.create()

OPCUA.Server.Value

Short description

The Value crown allows to create, access and modify OPC UA values as specified in OPC UA specification parts 3, 4 and 6. Values can be (1) used to set or get the value of OPC UA variable or variable type nodes, (2) used as parameters to OPC UA method calls, (3) or used as parameters to OPC UA events. Values can be (1) simple, built-in OPC UA data types (e.g., int16, string, an enumeration value), (2) OPC UA structures containing (optional) named fields, (3) OPC UA unions, (4) or arrays of the aforementioned value types. Fields of a Value are addressed by paths. The empty path "" addresses the current element. All OPC UA built-in data types are accessed through using an empty path. In structures and unions, fields have unique names. They can be addressed by their names. Nested fields are separated by dots ("."). Array members are addressed by zero-based indices in brackets ([]).

Overview

getActiveUnionField(), getArrayLength(), getOptionalFieldState(), getValue(), resizeArray(), setArrayToNull(), setOptionalFieldState(), setValue(), switchUnionField()

Functions

getActiveUnionField()

Short description

Get the field that is currently active at the union

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Value
path	STRING	The path of the member

Return values
Name	Type	Description
field	ENUM UnionField	The field that is currently set active

Sample

OPCUA.Server.Value.getActiveUnionField(handle, "")

getArrayLength()

Short description

Get the current element count of an array

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Value
path	STRING	The path of the member to be resized

Return values
Name	Type	Description
length	INT	The current element count of the array or -1 if the selected path is not an array or NULL

Sample

OPCUA.Server.Value.getArrayLength(handle, "")

getOptionalFieldState()

Short description

Get the state of an optional structure field

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Value
path	STRING	The path of the member to be enabled/ disable

Return values
Name	Type	Description
state	AUTO	The current state of the field, or nil if field is non-optional.

Sample

OPCUA.Server.Value.getOptionalFieldState(handle, "")

getValue()

Short description

Get the builtin value(s) contained in the Value instance.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Value
path	STRING	The path of the member

Return values
Name	Type	Description
value	AUTO	The builtin value

Sample

local value = OPCUA.Server.Value.getValue(handle, "some_field.an_integer")

resizeArray()

Short description

Set the new element count of an array

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Value
newSize	INT	The new element count of the array
path	STRING	The path of the member

Sample

OPCUA.Server.Value.resizeArray(handle, 10, "")

setArrayToNull()

Short description

Set an array to NULL. (In OPC UA, array can have length 0 OR be null.)

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Value
path	STRING	The path of the member to be nulled

Sample

OPCUA.Server.Value.setArrayToNull(handle, "")

setOptionalFieldState()

Short description

Enable / disable an optional field of a structure

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Value
state	ENUM OptionalFieldState	The new field state
path	STRING	The path of the member to be enabled/ disabled

Sample

OPCUA.Server.Value.setOptionalFieldState(handle, "ENABLED", "")

setValue()

Short description

Sets the builtin value of the Value instance.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Value
value	AUTO	The builtin value
path	STRING	The path of the member

Sample

OPCUA.Server.Value.setValue(handle, 123, "some_field.an_integer")

switchUnionField()

Short description

Set the field of a union that is active

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the OPC UA Value
field	ENUM UnionField	The field to be set active
path	STRING	The path of the member to be activated

Sample

OPCUA.Server.Value.switchUnionField(handle, "FIELD_1", "")

Object

Short description

Provides functionality to work on object datatypes. Persistence is one of the main features. Currently supported data format: JSON (file extension ".json") and MessagePack (file extension .msgpack)

Overview

clone(), deserialize(), getType(), load(), save(), serialize(), toConst()

Functions

clone()

Short description

Creates a full deep copy clone of the provided object/handle. Can fail if the object/handle does not support cloning.

Parameters
Name	Type	Description
obj	CONST_AUTO	The object/handle to clone

Return values
Name	Type	Description
cloneObj	AUTO	The cloned object/handle. Nil if clone was not possible or not successful.

deserialize()

Short description

De-Serializes an object from a byte array

Parameters
Name	Type	Description
serializedData	BINARY	The serialized data
dataFormat	ENUM DataFormat	Data format specification

Return values
Name	Type	Description
obj	AUTO	A valid object/handle (or multiple of them) in case of success, no value in case of error

Sample

obj = Object.deserialize(data, "JSON")

getType()

Short description

Returns the type name of an object/handle which is the CROWN name assigned to the object

Parameters
Name	Type	Description
obj	CONST_AUTO	The object/handle to get the type from

Return values
Name	Type	Description
crownName	STRING	The name of the CROWN the object is assigned to

load()

Short description

Loads an object/handle content from a file. When the type parameter is not passed, the data format is guessed from the file extension.

Parameters
Name	Type	Description
fileName	STRING	The file where the data should read from
dataFormat	ENUM DataFormat	Optional data format specification. If omitted, it is guessed from the file name extension

Return values
Name	Type	Description
obj	AUTO	A valid object/handle (or multiple of them) in case of success, no value in case of error

Sample

object = Object.load("private/FileContent.json")

save()

Short description

Saves an object content to a file. If the data type enumeration is not passed as argument, the file extension is used to guess the data format.

Parameters
Name	Type	Description
obj	CONST_AUTO	The object/handle(s) to be saved. Only objects/handle types are supported. Saving of handles is reserved for future use.
fileName	STRING	The file where the data should be written to
dataFormat	ENUM DataFormat	Optional data format specification. If omitted, it is guessed from the file name extension

Return values
Name	Type	Description
success	BOOL	true when saving succeeded, false when there was an error. In case of errors, please look at the console for error information

Sample

success = Object.save(data, "private/FileContent.json")

serialize()

Short description

Serializes an object to a byte array

Parameters
Name	Type	Description
obj	CONST_AUTO	The object/handle(s) to be serialized. Only objects/handle types are supported. In case of handles, the configuration data is saved which was passed at the creation of the handle (if supported by the handle)
dataFormat	ENUM DataFormat	Data format specification

Return values
Name	Type	Description
serializedData	BINARY	The serialized data in case of success, no data otherwise

Sample

buf = Object.serialize(data, "JSON")

toConst()

Short description

Return the provided object explicitly as const object. This is useful to guarantee further const usage of the object. The input object is not touched and stays non-const.

Parameters
Name	Type	Description
obj	CONST_OBJECT [API:DataFormat:]	The object to return as const

Return values
Name	Type	Description
constObj	CONST_OBJECT [API:DataFormat:]	The same object but as const

Parameters

Short description

Provides access to parameters of the current application and the device parameters. This CROWN implements the AppSpace Parameters component. Read more about Parameters in the AppSpace documentation. Parameters could be basic types (int, bool, …) which can be accessed over "Parameters.get" and "Parameters.set" in this case. Parameters could be complex types (array, struct, …) which can be accessed over "Parameters.getNode" and "Parameters.setNode" in this case. Complex parameters are represented as "Parameters.Node" object and can be accessed and navigated over its functions.

Overview

apply(), get(), getNode(), loadAllDefaults(), loadBlockDefaults(), loadDefault(), loadPermanent(), savePermanent(), set(), setNode()

OnAllDefaultsLoaded, OnParametersChanged, OnParametersLoaded, OnParametersSaved

Functions

apply()

Short description

Parameters of the device are not automatically activated when calling the Parameters.set/setNode function. This function has to be called after using the "Parameters.set" or "Parameters.setNode" function so that they are applied on the device. Please note that the parameters are not directly updated if this function returns. The event "Parameters.OnParametersChanged" is triggered after calling this function when the parameters are updated to inform the device and other applications.

Sample

Parameters.apply()

get()

Short description

Returns the value of the specified parameter. Please note that all parameter repositories of the device are considered, not only application parameters. This function can also access just one leaf of a complex parameter by addressing over xPath syntax. The numbers used for array access are interpreted as hex-numbers. If read fails function returns nothing. It can fail if the parameter is not existing or it has a complex type. If it has a complex type please use the "Parameters.getNode" function.

Parameters
Name	Type	Description
varName	STRING	The name or path of the parameter to be read

Return values
Name	Type	Description
varValue	AUTO	The value(s) of the parameter. Nil if parameter does not exist or type not possible. The type which is returned depends on the value of the parameter.

Sample

-- Usage possibilities:
local theParam = Parameters.get("LocationName") -- single string parameter get
local subValue = Parameters.get("MyParameter/subValue") -- get over xpath
local arrayValue = Parameters.get("MyArray[0]") -- get first array value

getNode()

Short description

Returns a copy of the parameter as "Parameters.Node" to navigate in the parameter structure. This function can also access just one leaf of a complex parameter by addressing over xPath syntax. The numbers used for array access are interpreted as hex-numbers. The return object is a copy of the current parameter values. If it is changed, the "Parameters.setNode" function has to be called with the object.

Parameters
Name	Type	Description
varName	STRING	The name or path of the parameter to be written

Return values
Name	Type	Description
nodeObjectCopy	OBJECT Parameters.Node	The copy of the node object of the parameter or nil if parameter does not exist

Sample

-- Get a parameter node, get all member nodes of it and print how much nodes the parameter has:
local theNode = Parameters.getNode("MyComplexParameter")
local subNodes = Parameters.Node.getNode(theNode)
print("Number of subnodes in MyComplexParameter: " .. ##subNodes)

loadAllDefaults()

Short description

Loads the default values of all parameters of the device. It affects all parameters of all apps as well as the parameters of the device. Concretely this function sets all parameters to factory defaults. This function does NOT do a save permanent.

Sample

Parameters.loadAllDefaults()

loadBlockDefaults()

Short description

Loads the default values of all app parameters in the specified block of all loaded parameter files. This function does NOT work with device parameters, only with app parameters.

Parameters
Name	Type	Description
blockName	STRING	The name of the block in the app parameters file(s)

Return values
Name	Type	Description
success	BOOL	True if successfully restored the default values for the block(s). False on error or block does not exist in no parameters file

loadDefault()

Short description

Loads the default value of the specified app parameter. This function does NOT work with device parameters, only with app parameters.

Parameters
Name	Type	Description
varName	STRING	The name or path of the parameter to be load the default value

Return values
Name	Type	Description
success	BOOL	True if successfully restored the default value- False on error or block does not exist

Sample

Parameters.loadDefault("MyParameter")

loadPermanent()

Short description

This function restores all current permanent stored values of all application and device parameters. Per default a permanent load is done automatically on bootup of the device. This function blocks until the restoring is done. There is no apply on the parameters done and no OnParametersChanged event thrown. The user has to call the apply() function manually.

Sample

Parameters.loadPermanent()

savePermanent()

Short description

This function stores the current parameter values of all applications and the device permanently. The values of the permanent stored parameters are automatically loaded on bootup of the device again. This function blocks until the storing is done.

Sample

Parameters.savePermanent()

set()

Short description

Sets the value of the specified parameter. Please note that all parameter repositories of the device are considered, not only application parameters. This function can also access just one leaf of a complex parameter by addressing over xPath syntax. The numbers used for array access are interpreted as hex-numbers. If set fails the function returns false. Parameter values are directly updated and CoLa events are directly fired (also if the values are identical), but device parameters are not directly activated. Therefore if device parameters have been changed, the "Parameters.apply" function needs to be called so that they get active.

Parameters
Name	Type	Description
varName	STRING	The name or path of the parameter to be written
varValue	AUTO	The value(s) of the parameter.

Return values
Name	Type	Description
success	BOOL	True if successfully set. False if parameter does not exist or type does not match the parameter declaration

Sample

-- Usage possibilities:
local bSuccess = Parameters.set("LocationName", "Mydevice") -- set single string parameter value
local bSuccess = Parameters.set("MyParameter/memberString", "stringValue") -- set sub parameter value
local bSuccess = Parameters.set("MyArray[0]", 123) -- set first array value

setNode()

Short description

Sets the value of the specified parameters as "Parameters.Node". This function can also access just one leaf of a complex parameter by addressing over xPath syntax. The numbers used for array access are interpreted as hex-numbers. The specified node content and structure has to match the parameter declaration. A matching node for a parameter can be get over "Parameters.getNode". If set fails the function returns false. Parameter values are directly updated and CoLa events are directly fired (also if the values are identical), but device parameters are not directly activated. Therefore if device parameters have been changed, the "Parameters.apply" function needs to be called so that they get active.

Parameters
Name	Type	Description
varName	STRING	The name or path of the parameter to be written
nodeObject	CONST_OBJECT Parameters.Node	The node object with the new values. The node structure has to match the parameter

Return values
Name	Type	Description
success	BOOL	True if successfully set. False if parameter does not exist or node structure does not match the parameter declaration

Sample

-- Get a parameter node, modify it and write the whole parameter:
local theNode = Parameters.getNode("MyComplexParameter")
Parameters.Node.set(theNode, "memberString", "stringValue")
Parameters.setNode("MyComplexParameter", theNode)

Events

OnAllDefaultsLoaded

Short description

This event is notified when the all parameter default values were loaded. A all-defaults-loading can be triggered by the API function "Parameters.loadAllDefaults" and over the command interface.

OnParametersChanged

Short description

This event is notified when the parameters of the application or the device might have changed. There is no information if parameters are really changed or which parameters are changed. This event might also be thrown even when were no parameters changed at all. The user has to read its parameters using the "Parameters.get" function and detect himself if it has changed.

OnParametersLoaded

Short description

This event is notified when the parameters were restored from permanent storage. A load permanent is triggered by the API function "Parameters.loadPermanent" or over the command interface.

OnParametersSaved

Short description

This event is notified when the parameters were stored permanently. A save permanent is triggered by the API function "Parameters.savePermanent" or over the command interface.

Parameters.Listener

Short description

Provides functionality to register for or poll changes of parameter values. One listener could listen to several parameters by using the add()-function multiple times. The user could register for an OnChanged-event to get every write to a listened parameter. Alternatively it could only use isChanged()- and clearChanged()-functions and e.g. call them during 'Engine.OnStarted' event handling. This functionality does NOT work with device parameters, only with app parameters.

Overview

add(), clearChanged(), create(), deregister(), isChanged(), register()

OnChanged

Functions

add()

Short description

Adds a parameter name to listen to

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of Parameters.Listener
paramName	STRING	The name of the parameter to listen to

Return values
Name	Type	Description
success	BOOL	True if successfully added. False if not possible or parameter does not exist

Sample

Parameters.Listener.add(handle, "MyParameterName")

clearChanged()

Short description

Clears a changed state manually.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of Parameters.Listener

Sample

Parameters.Listener.clearChanged(handle)

create()

Short description

Creates a new listener instance. The listener stays active as long as this instance exists.

Return values
Name	Type	Description
handle	HANDLE	The new Parameters.Listener instance

Sample

handle = Parameters.Listener.create()

deregister()

Short description

This function is used to deregister from any registered event of the handle.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
eventname	STRING	The event to deregister from
callback	STRING	The function name which was registered on the event

Return values
Name	Type	Description
success	BOOL	True if successfully deregistered. False if event does not exist or callback wasn’t registered.

isChanged()

Short description

Polls the current changed state. State needs to be reset manually using the clearChanged()-function.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of Parameters.Listener

Return values
Name	Type	Description
changed	BOOL	True if the parameters was

Sample

local bIsChanged = Parameters.Listener.isChanged(handle)

register()

Short description

This function is used to register for any event of the handle.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
eventname	STRING	The event to register to
callback	STRING	The function name to call on the event occurrence

Return values
Name	Type	Description
success	BOOL	True if successfully registered. False if event does not exist.

Events

OnChanged

Short description

Is thrown if the value of the parameters has changed or is written with same value

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of Parameters.Listener

Sample

Parameters.Listener.register(handle, "OnChanged", "handleChanged")

Parameters.Node

Short description

A "Parameters.Node" object represents a parameter composition or one leaf of it. If can be used to navigate in the tree of the complex parameter to access or modify values. A node cannot be created by this CROWN, but it is returned e.g. from "Parameters.getNode".

Overview

get(), getAllNodes(), getArraySize(), getNode(), set(), setAllNodes(), setArraySize(), setNode()

Functions

get()

Short description

Gets the single value or all values of this node or of a child node addressed by a relativePath. This function can also access just one leaf of a complex parameter by addressing over xPath syntax. The numbers used for array access are interpreted as hex-numbers. If the accessed leaf is a struct or array, then use the getNode()-function instead.

Parameters
Name	Type	Description
nodeObject	CONST_OBJECT Parameters.Node	The instance of the object to use
relativePath	STRING	The name or relativePath to access. Nil if accessing this node

Return values
Name	Type	Description
varValue	AUTO	The value(s) of the parameter. Nil if parameter does not exist or type not possible. The type which is returned depends on the value of the parameter.

Sample

-- Usage possibilities:
local singleValue = Parameters.Node.get(node) -- if the node is a single value get it
local singleSubValue = Parameters.Node.get(node, "subValue") -- get the member value "subValue" of this node if it is a struct
local arraySubValue = Parameters.Node.get(node, "subArray") -- get all the member array values of member "subArray" if it is a struct
local arrayValue = Parameters.Node.get(node, "[0]") -- get the first index value of an array node. Index number is interpreted as hex-number.
local singleSubArrayValue = Parameters.Node.get(node, "subMember/subArray[0]") -- get the first value of the subArray which is member of the subMember struct. Index number is interpreted as hex-number.

getAllNodes()

Short description

Gets copies of all children nodes of this node or of a child node addressed by a relativePath. This function can also access just one leaf of a complex parameter by addressing over xPath syntax. The numbers used for array access are interpreted as hex-numbers. It is possible to get the children of structs and arrays.

Parameters
Name	Type	Description
nodeObject	CONST_OBJECT Parameters.Node	The instance of the object to use
relativePath	STRING	The name or relativePath to access. Nil if accessing this node

Return values
Name	Type	Description
nodeObjectCopies	OBJECT Parameters.Node	The copies of the node objects of the parameter or nil if parameter does not exist

Sample

-- Usage possibilities:
local subNodes = Parameters.Node.getAllNodes(node) -- get all sub nodes of the node
local subNodes = Parameters.Node.getAllNodes(node, "subMember") -- get all member nodes of a sub struct

getArraySize()

Short description

Returns the size if this node is an array. If it is a flexible array, then the current size is returned.

Parameters
Name	Type	Description
nodeObject	CONST_OBJECT Parameters.Node	The instance of the object to use
relativePath	STRING	The name or relativePath to access. Nil if accessing this node

Return values
Name	Type	Description
size	INT	The current size of the array. Nil if it is not an array

Sample

local arrSize = Parameters.Node.getArraySize(node)

getNode()

Short description

Gets a copy of a single node of this node or of a child node addressed by a relativePath. This function can also access just one leaf of a complex parameter by addressing over xPath syntax. The numbers used for array access are interpreted as hex-numbers.

Parameters
Name	Type	Description
nodeObject	CONST_OBJECT Parameters.Node	The instance of the object to use
relativePath	STRING	The name or relativePath to access. Nil if accessing this node

Return values
Name	Type	Description
nodeObjectCopy	OBJECT Parameters.Node	The copy of the node object of the parameter or nil if parameter does not exist

Sample

-- Usage possibilities:
local subNode = Parameters.Node.getNode(node, "childName") -- get one member node named "childName"
local subArraynode = Parameters.Node.getNode(node, "subMember/subArray[0]") -- get the first value of the subArray which is member of subMember struct. Index number is interpreted as hex-number.

set()

Short description

Sets the single value or all values of this node or of a child node addressed by a relativePath. This function can also access just one leaf of a complex parameter by addressing over xPath syntax. The numbers used for array access are interpreted as hex-numbers. If set fails the function returns false.

Parameters
Name	Type	Description
nodeObject	OBJECT Parameters.Node	The instance of the object to use
varValue	AUTO	The value(s) of the parameter. Nil if parameter does not exist or type not possible. The type has to match the declaration of the parameter.
relativePath	STRING	The name or relativePath to access. Nil if accessing this node

Return values
Name	Type	Description
success	BOOL	True if successfully set. False if parameter does not exist or type does not match the parameter declaration

Sample

-- Usage possibilities:
local bSuccess = Parameters.Node.set(node, "stringValue") -- Set a single value to this node if it is a string parameter node
local bSuccess = Parameters.Node.set(node, "stringValue", "memberString") -- Set a value to one member of this node if it is a struct

setAllNodes()

Short description

Sets all specified nodes as children to this node or to a child node addressed by a relativePath. This function can also access just one leaf of a complex parameter by addressing over xPath syntax. The numbers used for array access are interpreted as hex-numbers. The specified node content and structure has to match the current node parameter declaration. It is possible to set the children of structs and arrays. If set fails the function returns false. This node can be inconsistent in case of fail.

Parameters
Name	Type	Description
nodeObject	OBJECT Parameters.Node	The instance of the object to use
valueObject	CONST_OBJECT Parameters.Node	The node objects with the new values. The node structure has to match the parameter. Values are copied to the nodeObject.
relativePath	STRING	The name or relativePath to access. Nil if accessing this node

Return values
Name	Type	Description
success	BOOL	True if successfully set. False if parameter does not exist or node structure does not match the parameter declaration

Sample

-- Usage possibilities:
local bSuccess = Parameters.Node.setAllNodes(node, nodeVector) -- set the nodes of the vector to this one

setArraySize()

Short description

Sets the size of this node if it is an array and the size or the array is declared as flexible

Parameters
Name	Type	Description
nodeObject	OBJECT Parameters.Node	The instance of the object to use
size	INT	The new size of the array
relativePath	STRING	The name or relativePath to access. Nil if accessing this node

Return values
Name	Type	Description
success	BOOL	True if successful set. False if array size does not match the parameter declaration.

Sample

Parameters.Node.setArraySize(node, 5)

setNode()

Short description

Sets the single node of this node or of a child node addressed by a relativePath. This function can also access just one leaf of a complex parameter by addressing over xPath syntax. The numbers used for array access are interpreted as hex-numbers. The specified node content and structure has to match the current node parameter declaration. If set fails the function returns false.

Parameters
Name	Type	Description
nodeObject	OBJECT Parameters.Node	The instance of the object to use
valueObject	CONST_OBJECT Parameters.Node	The node object with the new values. The node structure has to match the parameter. Values are copied to the nodeObject.
relativePath	STRING	The name or relativePath to access. Nil if accessing this node

Return values
Name	Type	Description
success	BOOL	True if successfully set. False if parameter does not exist or node structure does not match the parameter declaration

Sample

-- Usage possibilities:
local bSuccess = Parameters.Node.setNode(node, otherNode) -- sets the values of another node to this one

Parameters.Validator

Short description

Provides functionality to hook in to parameter writes to decide if a write is allowed or not. One validator could validate several parameters by using the add()-function multiple times. The validator function can be set using the setCallback()-function. See description of the setCallback()-function for details about the callback implementation. This functionality does NOT work with device parameters, only with app parameters.

Overview

add(), create(), setCallback()

Functions

add()

Short description

Adds a parameter name to validate

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of Parameters.Validator
paramName	STRING	The name of the parameter to validate

Return values
Name	Type	Description
success	BOOL	True if successfully added. False if not possible or parameter does not exist

Sample

Parameters.Validator.add(handle, "MyParameterName")

create()

Short description

Creates a new validator instance. The validator stays active as long as this instance exists.

Return values
Name	Type	Description
handle	HANDLE	The new Parameters.Validator instance

Sample

handle = Parameters.Validator.create()
handle:add("MyParam")
function callback(paramName, paramNode)
  -- Use paramName and paramNode to decide if return true/false
  return bOk
end
handle:setCallback(handle, callback)

setCallback()

Short description

Sets the validator callback function which is called upon writes to the added parameters. The function gets called with two parameters: The parameter name and a Parameters.Node const-object containing the value which wants to be written. It is not guaranteed that the second parameter with the value object is available. If the parameter write is done over communication interfaces, it is present, but if the write is done using Parameters.set()-function, it is not available. The function gets called in blocking mode and the current parameter-write is blocked until the function returns. If the function returns true, the parameter-write is done. If false, then there is an error thrown on the CoLa command interface with number 0x4 (condition wrong)

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of Parameters.Validator
funcCallback	STRING	The function name to be called for validation. Needs to have a specific signature, read more about in the function documentation.

Sample

function callback(paramName, paramNode)
  -- get values from "paramNode" using Parameters.Node-functions
  -- if writing should be done, return true. Otherwise return false.
  return bOk
end
Parameters.Validator.setCallback(handle, callback)

Point

Short description

Represents a point/vector in 2D or 3D

Functions

add()

Short description

Add the corresponding components of two points.

Parameters
Name	Type	Description
point1	CONST_OBJECT Point	Input point 1
point2	CONST_OBJECT Point	Input point 2

Return values
Name	Type	Description
pointOut	OBJECT Point	Output point

Sample

pointOut = Point.add(point1, point2)

addConstant()

Short description

Add a constant to each component.

Parameters
Name	Type	Description
pointIn	CONST_OBJECT Point	Input point
constant	FLOAT	The constant

Return values
Name	Type	Description
pointOut	OBJECT Point	Output point

Sample

pointOut = Point.addConstant(pointIn, constant)

clone()

Short description

Create a copy of a point.

Parameters
Name	Type	Description
point	CONST_OBJECT Point	Input point

Return values
Name	Type	Description
clonedPoint	OBJECT Point	Copy of the input point

Sample

clonedPoint = Point.clone(point)

create()

Short description

Create 2D or 3D point(s). The third z-coordinate input is optional, if omitted a 2D point is created, otherwise a 3D point. Vector input is allowed to create vectors of points. The input vectors must then all be of equal length. The following input combinations are allowed: Two scalar floats give a 2D point (x,y) Three scalar floats give a 3D point (x,y,z) Two vectors of equal length give a vector of 2D points Three vectors of equal length give a vector of 3D points

Parameters
Name	Type	Description
x	FLOAT	X coordinate, a scalar or vector.
y	FLOAT	Y coordinate, a scalar or vector.
z	FLOAT	Z coordinate, a scalar or vector. Optional: if omitted, 2D points will be created.

Return values
Name	Type	Description
point	OBJECT Point	The created point or vector of points.

Sample

point = Point.create({1.0, 2.0}, {3.0, 4.0})

cross()

Short description

Calculates the cross product of two point vectors (only 3D). The cross product is anti-commutative: a x b = -(b x a)

See also

Point.dot

Parameters
Name	Type	Description
a	CONST_OBJECT Point	Input point
b	CONST_OBJECT Point	Input point

Return values
Name	Type	Description
product	OBJECT Point	The cross product

Sample

product = Point.cross(a, b)

divide()

Short description

Divide the components of the first point with the corresponding components of the second point.

Parameters
Name	Type	Description
point1	CONST_OBJECT Point	Input point 1
point2	CONST_OBJECT Point	Input point 2

Return values
Name	Type	Description
pointOut	OBJECT Point	Output point

Sample

pointOut = Point.divide(point1, point2)

divideConstant()

Short description

Divide each component with a constant.

Parameters
Name	Type	Description
pointIn	CONST_OBJECT Point	Input point
constant	FLOAT	The constant

Return values
Name	Type	Description
pointOut	OBJECT Point	Output point

Sample

pointOut = Point.divideConstant(pointIn, constant)

dot()

Short description

Calculates the dot product of two point vectors of the same dimensionality (e.g. x1*x2+y1*y2+z1*z2).

See also

Point.cross

Parameters
Name	Type	Description
point1	CONST_OBJECT Point	Input point
point2	CONST_OBJECT Point	Input point

Return values
Name	Type	Description
product	FLOAT	The dot product

Sample

product = Point.dot(point1, point2)

getDistance()

Short description

Compute the distance between the two points of the same dimensionality (2D or 3D).

Parameters
Name	Type	Description
point1	CONST_OBJECT Point	Input point
point2	CONST_OBJECT Point	Input point

Return values
Name	Type	Description
distance	FLOAT	Distance between the points

Sample

distance = Point.getDistance(point1,point2)

getDistanceToLine()

Short description

Calculates the distance from a point to a line (2D/3D).

See also

Point.getDistanceToPlane

Parameters
Name	Type	Description
pointIn	CONST_OBJECT Point	Input point
line	CONST_AUTO	Input line (Shape/Shape3D).

Return values
Name	Type	Description
distance	FLOAT	The distance from point to line or nil for invalid input combination

Sample

local distance = Point.getDistanceToLine(pointIn, line)

getDistanceToPlane()

Short description

Calculates the distance from a point to a plane (only 3D).

Parameters
Name	Type	Description
pointIn	CONST_OBJECT Point	Input point
plane	CONST_OBJECT Shape3D	Input plane.

Return values
Name	Type	Description
distance	FLOAT	The distance from point to plane

Sample

local distance = Point.getDistanceToPlane(pointIn, plane)

getX()

Short description

Get the X coordinate of a point.

Parameters
Name	Type	Description
point	CONST_OBJECT Point	Input point

Return values
Name	Type	Description
x	FLOAT	x coordinate of the point

Sample

x = Point.getX(point)

getXY()

Short description

Get the X and Y coordinates of a point.

Parameters
Name	Type	Description
point	CONST_OBJECT Point	Input point

Return values
Name	Type	Description
x	FLOAT	x coordinate of the point
y	FLOAT	y coordinate of the point

Sample

x,y = Point.getXY(point)

getXYZ()

Short description

Get the X, Y and Z coordinates of a point (only 3D).

Parameters
Name	Type	Description
point	CONST_OBJECT Point	Input point

Return values
Name	Type	Description
x	FLOAT	x coordinate of the point
y	FLOAT	y coordinate of the point
z	FLOAT	z coordinate of the point

Sample

x,y,z = Point.getXYZ(point)

getY()

Short description

Get the Y coordinate of a point.

Parameters
Name	Type	Description
point	CONST_OBJECT Point	Input point

Return values
Name	Type	Description
y	FLOAT	y coordinate of the point

Sample

y = Point.getY(point)

getZ()

Short description

Get the Z coordinate of a point (only 3D).

Parameters
Name	Type	Description
point	CONST_OBJECT Point	Input point

Return values
Name	Type	Description
z	FLOAT	z coordinate of the point

Sample

z = Point.getZ(point)

is2D()

Short description

Check if a point is a 2D point.

Parameters
Name	Type	Description
point	CONST_OBJECT Point	Input point

Return values
Name	Type	Description
ret	BOOL	True if 2D point, otherwise false

Sample

ret = Point.is2D(point)

is3D()

Short description

Check if a point is a 3D point.

Parameters
Name	Type	Description
point	CONST_OBJECT Point	Input point

Return values
Name	Type	Description
ret	BOOL	True if 3D point, otherwise false

Sample

ret = Point.is3D(point)

isFinite()

Short description

Check if a point is finite, i.e. none of the values is Inf/NaN.

Parameters
Name	Type	Description
point	CONST_OBJECT Point	Input point

Return values
Name	Type	Description
ret	BOOL	True if finite point, otherwise false

Sample

ret = Point.isFinite(point)

isZero()

Short description

Returns true if all coordinates are zero.

Parameters
Name	Type	Description
point	CONST_OBJECT Point	Input point

Return values
Name	Type	Description
ret	BOOL	True if all coordinates are zero, otherwise false

Sample

ret = Point.isZero(point)

multiply()

Short description

Multiply the corresponding components of two points.

Parameters
Name	Type	Description
point1	CONST_OBJECT Point	Input point 1
point2	CONST_OBJECT Point	Input point 2

Return values
Name	Type	Description
pointOut	OBJECT Point	Output point

Sample

pointOut = Point.multiply(point1, point2)

multiplyConstant()

Short description

Multiply each component with a constant.

Parameters
Name	Type	Description
pointIn	CONST_OBJECT Point	Input point
constant	FLOAT	The constant

Return values
Name	Type	Description
pointOut	OBJECT Point	Output point

Sample

pointOut = Point.multiplyConstant(pointIn, constant)

negate()

Short description

Returns the negated point vector (every component changes its sign).

Parameters
Name	Type	Description
pointIn	CONST_OBJECT Point	Input point

Return values
Name	Type	Description
pointOut	OBJECT Point	The negated point

Sample

pointOut = Point.negate(pointIn)

norm()

Short description

Calculates different types of non-negative vector norms. If no enumeration is provided, the "L-2-Norm" will be calculated, which represents the magnitude or length of the point vector.

Parameters
Name	Type	Description
pointIn	CONST_OBJECT Point	Input point
type	ENUM NormType	Norm type enumeration

Return values
Name	Type	Description
norm	FLOAT	The norm

Sample

norm = Point.norm(pointIn)

normalize()

Short description

Returns the unit vector (length=1) with the same direction or nil if the input point vector has the length 0.

Parameters
Name	Type	Description
pointIn	CONST_OBJECT Point	Input point

Return values
Name	Type	Description
pointOut	OBJECT Point	The normalized point vector or nil

Sample

pointOut = Point.normalize(pointIn)

projectOntoPlane()

Short description

Projects one or multiple points onto a plane (only 3D).

See also

Point.getDistanceToPlane

Parameters
Name	Type	Description
pointIn	CONST_OBJECT Point	Input point(s)
plane	CONST_OBJECT Shape3D	The projection plane.

Return values
Name	Type	Description
pointOut	OBJECT Point	The point(s) on the plane

Sample

pointOut = Point.projectOntoPlane(pointIn, plane)

setX()

Short description

Set the X coordinate of a point.

Parameters
Name	Type	Description
point	OBJECT Point	Input point
x	FLOAT	X coordinate

Sample

Point.setX(point, x)

setXY()

Short description

Set the X and Y coordinates of a point.

Parameters
Name	Type	Description
point	OBJECT Point	Input point
x	FLOAT	X coordinate
y	FLOAT	Y coordinate

Sample

Point.setXY(point, x, y)

setXYZ()

Short description

Set the X, Y and Z coordinates of a point (only 3D).

Parameters
Name	Type	Description
point	OBJECT Point	Input point
x	FLOAT	X coordinate
y	FLOAT	Y coordinate
z	FLOAT	Z coordinate

Sample

Point.setXYZ(point, x, y, z)

setY()

Short description

Set the Y coordinate of a point.

Parameters
Name	Type	Description
point	OBJECT Point	Input point
y	FLOAT	Y coordinate

Sample

Point.setY(point, y)

setZ()

Short description

Set the Z coordinate of a point (only 3D).

Parameters
Name	Type	Description
point	OBJECT Point	Input point
z	FLOAT	Z coordinate

Sample

Point.setZ(point, z)

subtract()

Short description

Subtract the corresponding components of the second point from those of the first point.

Parameters
Name	Type	Description
point1	CONST_OBJECT Point	Input point 1
point2	CONST_OBJECT Point	Input point 2

Return values
Name	Type	Description
pointOut	OBJECT Point	Output point

Sample

pointOut = Point.subtract(point1, point2)

subtractConstant()

Short description

Subtract a constant from each component.

Parameters
Name	Type	Description
pointIn	CONST_OBJECT Point	Input point
constant	FLOAT	The constant

Return values
Name	Type	Description
pointOut	OBJECT Point	Output point

Sample

pointOut = Point.subtractConstant(pointIn, constant)

toMatrix()

Short description

Converts a point or a vector of points to a matrix.

Parameters
Name	Type	Description
point	CONST_OBJECT Point	Input point, or vector of points to convert to a matrix.
storeInColumns	BOOL	When true the points are placed in the columns of the matrix, when false in the rows of the matrix.

Return values
Name	Type	Description
matrix	OBJECT Matrix	Matrix created from the points.

Sample

matrix = Point.toMatrix(point, storeInColumns)

toString()

Short description

Get a string representation of the point.

Parameters
Name	Type	Description
point	CONST_OBJECT Point	Input point

Return values
Name	Type	Description
str	STRING	String representation of the point

Sample

print("The point is: " .. Point.toString(point))

transform()

Short description

Transforms point or a vector of points. For 2D points a 2D transform must be supplied, for 3D points a 3D transform.

See also

Transform

Parameters
Name	Type	Description
point	CONST_OBJECT Point	Input point, or vector of points.
transform	CONST_OBJECT Transform	Transform to apply.

Return values
Name	Type	Description
transformedPoint	OBJECT Point	Transformed point(s).

Sample

transformedPoint = Point.transform(point, transform)

PointCloud

Short description

Iconic object for points in a 3D Cartesian coordinate system.

Functions

appendPoint()

Short description

Appends a new point to the specified point cloud.

Parameters
Name	Type	Description
inputCloud	OBJECT PointCloud	Point cloud to append the point to
x	FLOAT	X value in [mm]
y	FLOAT	Y value in [mm]
z	FLOAT	Z value in [mm]
intensity	FLOAT	Intensity value

Sample

PointCloud.appendPoint(inputCloud, x, y, z, intensity)

clone()

Short description

Returns a duplicated instance of the input cloud. This is a full copy and might be very slow dependent on the cloud size.

Parameters
Name	Type	Description
inputCloud	CONST_OBJECT PointCloud	The cloud to clone

Return values
Name	Type	Description
clone	OBJECT PointCloud	The new cloned cloud object

Sample

local clone = PointCloud.clone(inputCloud)

create()

Short description

Creates a new empty point cloud object

Parameters
Name	Type	Description
colorMode	ENUM ColorMode	The color mode of this point cloud. Defaults to "INTENSITY".

Return values
Name	Type	Description
newCloud	OBJECT PointCloud	The newly created cloud

Sample

local newCloud = PointCloud.create()

createFromPoints()

Short description

Creates a point cloud from a vector of Point objects containing the Cartesian coordinates and an optional intensity value or vector of intensity values. If the input points are only 2D, the z-coordinate of all points in the point cloud is set to 0.

Parameters
Name	Type	Description
points	CONST_OBJECT Point	Vector of Point objects containing the coordinates.
intensity	FLOAT	Select an intensity between 0 and 1 for the points in the point cloud. Input can be either a single value or one value per point. Default is 1.0.

Return values
Name	Type	Description
pointcloud	OBJECT PointCloud	The resulting point cloud.

Sample

local pointcloud = PointCloud.createFromPoints(points, intensity)

createFromVector()

Short description

Creates a point cloud from vectors of x, y, z and intensity values.

Parameters
Name	Type	Description
x	FLOAT	X values in [mm]
y	FLOAT	Y values in [mm]
z	FLOAT	Z values in [mm]
intensity	FLOAT	Intensity values

Return values
Name	Type	Description
pointcloud	OBJECT PointCloud	The resulting point cloud.

Sample

local pointcloud = PointCloud.createFromVector(x, y, z, intensity)

extractIndices()

Short description

Extract a number of points referenced by indices from a point cloud.

Parameters
Name	Type	Description
inputCloud	CONST_OBJECT PointCloud	The input point cloud.
indices	INT	Indices of the points which will be copied to the output cloud.
negative	BOOL	Set to true to invert the filter behavior (copy all points not in the indices vector), default is false.

Return values
Name	Type	Description
outputCloud	OBJECT PointCloud	The extracted point cloud or nil, if the input point cloud is empty.

Sample

local outputCloud = PointCloud.extractIndices(inputCloud, indices, negative)

getBoundingBox()

Short description

Compute the axis-aligned bounding box of all points in this cloud and return a Shape3D object.

See also

PointCloud.getBounds

Parameters
Name	Type	Description
inputCloud	CONST_OBJECT PointCloud	The input point cloud.

Return values
Name	Type	Description
box	OBJECT Shape3D	The bounding box or nil, if the input point cloud is empty.

Sample

local box = PointCloud.getBoundingBox(inputCloud)

getBounds()

Short description

Compute the axis-aligned bounding box of all points in this cloud and return the float values.

See also

PointCloud.getBoundingBox

Parameters
Name	Type	Description
inputCloud	CONST_OBJECT PointCloud	The input point cloud

Return values
Name	Type	Description
minX	FLOAT	X-value of minimum point [mm]
minY	FLOAT	Y-value of minimum point [mm]
minZ	FLOAT	Z-value of minimum point [mm]
maxX	FLOAT	X-value of maximum point [mm]
maxY	FLOAT	Y-value of maximum point [mm]
maxZ	FLOAT	Z-value of maximum point [mm]

Sample

local minX, minY, minZ, maxX, maxY, maxZ = PointCloud.getBounds(inputCloud)

getCentroid()

Short description

Compute the centroid (or geometric center) as the arithmetic mean position of all points in this cloud.

Parameters
Name	Type	Description
inputCloud	CONST_OBJECT PointCloud	The input point cloud.

Return values
Name	Type	Description
centroid	OBJECT Point	The centroid or nil, if the input point cloud is empty.

Sample

local centroid = PointCloud.getCentroid(inputCloud)

getColor()

Short description

Get the RGBA color values of the specified points in the point cloud. Works only if the point cloud’s color mode is "RGBA".

See also

PointCloud.setColor

Parameters
Name	Type	Description
inputCloud	CONST_OBJECT PointCloud	The input point cloud
indices	INT	Indices of the points to get the color from

Return values
Name	Type	Description
red	INT	Red color component (single value or vector of same length as indices) or nil
green	INT	Green color component (single value or vector of same length as indices) or nil
blue	INT	Blue color component (single value or vector of same length as indices) or nil
alpha	INT	Alpha/opacity component (single value or vector of same length as indices) or nil

Sample

local red, green, blue, alpha = PointCloud.getColor(inputCloud, indices)

getColorMode()

Short description

Returns the color mode of the point cloud.

Parameters
Name	Type	Description
inputCloud	CONST_OBJECT PointCloud	The input point cloud

Return values
Name	Type	Description
colorMode	ENUM ColorMode	The color mode of this cloud

Sample

local colorMode = PointCloud.getColorMode(inputCloud)

getIntensity()

Short description

Get the intensity value of the specified points in the point cloud. Works only if the point cloud’s color mode is "INTENSITY".

See also

PointCloud.setIntensity

Parameters
Name	Type	Description
inputCloud	CONST_OBJECT PointCloud	The input point cloud
indices	INT	Indices of the points to get the intensity from

Return values
Name	Type	Description
intensity	FLOAT	Intensity (single value or vector of same length as indices) or nil

Sample

local intensity = PointCloud.getIntensity(inputCloud, indices)

getPoint()

Short description

Returns the x, y, z and intensity value of the specified point in the point cloud as single float values.

Parameters
Name	Type	Description
inputCloud	CONST_OBJECT PointCloud	The point cloud to get the point from
index	INT	Point index starting from 0

Return values
Name	Type	Description
x	FLOAT	X value in [mm]
y	FLOAT	Y value in [mm]
z	FLOAT	Z value in [mm]
intensity	FLOAT	Intensity value

Sample

local x,y,z,intensity = PointCloud.getPoint(inputCloud, index)

getPoint3D()

Short description

Returns the 3D coordinates of the specified point in the point cloud as Point object and the intensity as float value.

Parameters
Name	Type	Description
inputCloud	CONST_OBJECT PointCloud	The point cloud to get the point from
index	INT	Optional point index starting from 0

Return values
Name	Type	Description
point	OBJECT Point	The 3D coordinates as Point object.
intensity	FLOAT	Intensity value

Sample

local point, intensity = PointCloud.getPoint3D(inputCloud, index)

getPoints()

Short description

Returns the x, y, z and intensity value of all points in the point cloud as vectors of float values. This function is deprecated, please use PointCloud.toVector instead.

Parameters
Name	Type	Description
inputCloud	CONST_OBJECT PointCloud	Point cloud to get the points from

Return values
Name	Type	Description
x	FLOAT	X values in [mm]
y	FLOAT	Y values in [mm]
z	FLOAT	Z values in [mm]
intensity	FLOAT	Intensity values

Sample

local x,y,z,intensity = PointCloud.getPoints(inputCloud)

getSize()

Short description

Returns the dimensions of the point cloud.

Parameters
Name	Type	Description
inputCloud	CONST_OBJECT PointCloud	The point cloud to get the size from

Return values
Name	Type	Description
size	INT	The number of points in this cloud
width	INT	The width of the cloud if organized, total size if not
height	INT	The height of the cloud if organized, 1 if not

Sample

local size,width,height = PointCloud.getSize(inputCloud)

isDense()

Short description

Returns true if all the points in this point cloud have valid coordinates (i.e. not Inf/NaN). Clouds provided by a sensor may contain invalid points. This is typically used to ignore points with low confidence and at the same time keep the organized matrix structure of the cloud.

Parameters
Name	Type	Description
inputCloud	CONST_OBJECT PointCloud	The point cloud to get the attribute from

Return values
Name	Type	Description
isDense	BOOL	True if all the points in this point cloud have valid coordinates

Sample

local isDense = PointCloud.isDense(inputCloud)

isOrganized()

Short description

Returns true if the points in this point cloud are organized in rows and columns (i.e. height > 1). This is typically the case when the data has been created by a matrix sensor, e.g. in a time-of-flight camera.

Parameters
Name	Type	Description
inputCloud	CONST_OBJECT PointCloud	The point cloud to get the attribute from

Return values
Name	Type	Description
isOrganized	BOOL	True if the points in this point cloud are organized in rows and columns

Sample

local isOrganized = PointCloud.isOrganized(inputCloud)

load()

Short description

Load a point cloud from the specified file path. The format is defined by the file extension: .ply: Polygon File Format ("ascii" mode only) .pcd: Point Cloud Data File Format ("ascii", "binary" or "binary_compressed" mode) .ssr: SICK Sensor Record .json: JSON .msgpack: MessagePack

See also

Parameters
Name	Type	Description
filepath	STRING	The path and name of the file to load the point cloud from.

Return values
Name	Type	Description
loadedCloud	OBJECT PointCloud	The PointCloud object which is loaded.

Sample

local loadedCloud = PointCloud.load("resources/cloud.pcd")

merge()

Short description

Merge two point clouds by creating a new cloud and appending the points of both clouds to it. The color mode of both point clouds must be identical.

See also

PointCloud.mergeInplace

Parameters
Name	Type	Description
inputCloud1	CONST_OBJECT PointCloud	The first point cloud.
inputCloud2	CONST_OBJECT PointCloud	The second point cloud.

Return values
Name	Type	Description
mergedCloud	OBJECT PointCloud	The merged point cloud.

Sample

local mergedCloud = PointCloud.merge(inputCloud1, inputCloud2)

mergeInplace()

Short description

In-place version of the PointCloud.merge function that modifies the input point cloud. See base function for full documentation. The color mode of both point clouds must be identical.

See also

PointCloud.merge

Parameters
Name	Type	Description
inputCloud1	OBJECT PointCloud	The first point cloud. This point cloud is overwritten with the merged point cloud.
inputCloud2	CONST_OBJECT PointCloud	The second point cloud.

Return values
Name	Type	Description
result	OBJECT PointCloud	Reference to the result point cloud.

Sample

local result = PointCloud.mergeInplace(inputCloud1, inputCloud2)

resample()

Short description

Resample a point cloud using a 3D voxel grid. All points in one voxel are merged to their centroid by averaging their x, y, z and intensity values. It’s possible to specify a minimum number of points inside a voxel to ignore scattered points.

Detailed description

Data Reduction

PointCloud.resample creates an axis-aligned bounding box around the cloud which is subdivided into voxels (volumetric pixels) whose size can be defined with the voxelSizeX/Y/Z parameters.

All the points in one voxel of the grid are approximated with their centroid.
It’s possible to specify a minimum number of points inside a voxel to ignore scattered points.

Example: The four green points inside this voxel are replaced with their centroid (red point) in the output cloud.

PointCloud.sample chooses a number of random sample points with a uniform probability.

It’s a bit faster than resample and preserves the relative density of the cloud.

Input cloud with 50.000 points

PointCloud.sample(4000) - sample 4000 points

PointCloud.resample(5, 5, 5) - 5x5x5 mm voxel

PointCloud.resample(5, 5, 5, 10) - min. 10 points per voxel

Parameters
Name	Type	Description
inputCloud	CONST_OBJECT PointCloud	The input point cloud.
voxelSizeX	FLOAT	Voxel size in x-direction.
voxelSizeY	FLOAT	Voxel size in y-direction (uses voxelSizeX if not set).
voxelSizeZ	FLOAT	Voxel size in z-direction (uses voxelSizeX if not set).
minNumPoints	INT	Minimum number of points inside a voxel for creating a point in the output cloud, default is 1.

Return values
Name	Type	Description
resampledCloud	OBJECT PointCloud	The resampled point cloud.

Sample

local resampledCloud = PointCloud.resample(inputCloud, 5.0, 5.0, 5.0, 10)

save()

Short description

Save a point cloud to the specified file path. Overwrites the file if it already exists. The format is defined by the file extension: .ply: Polygon File Format ("ascii" mode only) .pcd: Point Cloud Data File Format ("ascii" or "binary" mode) .ssr: SICK Sensor Record .json: JSON (Optional useBinaryPCD parameter not supported). .msgpack: MessagePack (Optional useBinaryPCD parameter not supported).

See also

PointCloud.transformInplace

Parameters
Name	Type	Description
inputCloud	CONST_OBJECT PointCloud	The PointCloud object which is saved.
filepath	STRING	The path and name of the file to save the point cloud to.
useBinaryPCD	BOOL	Only applies for .pcd file format. If true write coordinates in binary mode instead of ASCII. Default is false.

Return values
Name	Type	Description
success	BOOL	Returns true if the point cloud has been successfully saved.

Sample

local success = PointCloud.save(inputCloud, "private/cloud.pcd")

setColor()

Short description

Set the RGBA color values of the specified points in the point cloud. Works only if the point cloud’s color mode is "RGBA".

Parameters
Name	Type	Description
inputCloud	OBJECT PointCloud	The input point cloud
indices	INT	Indices of the points to set the color for
red	INT	Red color component in range [0-255]. Must be either a single value or vector of same length as indices.
green	INT	Green color component in range [0-255]. Must be either a single value or vector of same length as indices.
blue	INT	Blue color component in range [0-255]. Must be either a single value or vector of same length as indices.
alpha	INT	Alpha/opacity component in range [0-255] (optional). Must be either a single value or vector of same length as indices or empty. Defaults to 255.

Return values
Name	Type	Description
success	BOOL	Returns true on success.

Sample

PointCloud.setColor(inputCloud, indices, red, green, blue)

setIntensity()

Short description

Set the intensity value of the specified points in the point cloud. Works only if the point cloud’s color mode is "INTENSITY".

Parameters
Name	Type	Description
inputCloud	OBJECT PointCloud	The input point cloud
indices	INT	Indices of the points to set the intensity for
intensity	FLOAT	Intensity value to set. Must be either a single value or vector of same length as indices.

Return values
Name	Type	Description
success	BOOL	Returns true on success.

Sample

PointCloud.setIntensity(inputCloud, indices, intensity)

setPoint()

Short description

Sets the x, y, z and intensity value of the specified point in the point cloud.

Parameters
Name	Type	Description
inputCloud	OBJECT PointCloud	Point cloud to set the point to
index	INT	Point index starting from 0
x	FLOAT	X value in [mm]
y	FLOAT	Y value in [mm]
z	FLOAT	Z value in [mm]
intensity	FLOAT	Intensity value, optional

Sample

PointCloud.setPoint(inputCloud, index, x, y, z, intensity)

toImage()

Short description

Create a range image from a pointcloud. The image is formed by projection of the point in the pointcloud onto the z-zero plane with normal (0, 0, 1). The x and y axes of the pointcloud are aligned with the x and y axes of the resulting image. The employed method is sometimes referred to as splatting, i.e., each point in the pointcloud is splatted onto the plane, writing its z-distance to a splat area given in pixels. Pixels which are not hit by any splats are marked as missing data. If such holes appear in the generated image try increasing the splat sizes, make the pixel sizes larger or use methods to fill missing data. The function can return two images, one with the z-distance in each pixel and one with the intensity value from the pointcloud. The output image is of type UINT16 and the size of the image is calculated based on the input parameters. Image world coordinate system handling: The world coordinate settings, e.g., origin in x,y,z and pixel sizes are set based on the input parameters to the function. Missing data handling: Pixels in the output range image and intensity image will be zero (missing data) if no point in the pointcloud had effect over that pixel. Missing data can be reduced by increasing the splat size or by post processing.

Keywords

convert, heightmap, project, splat

See also

Image.toPointCloud

Parameters
Name	Type	Description
pointcloud	CONST_OBJECT PointCloud	The input pointcloud.
box	CONST_OBJECT Shape3D	An axis-aligned box. All pointcloud points within this box are used for creating the image. Can for example be the bounding box of the pointcloud to include all points. The coordinate system origin of the resulting image is defined by the box.
pixelSizes	FLOAT	Vector defining the pixel sizes of the output image {x, y, z}. At least one value must be set and will then affect the x and y resolution. The z-resolution will be automatically estimated if unset.
splatSizes	INT	Optional vector of splat kernel sizes in the x and y dimensions. To select a splat size of 5 use {5}, for anisotropic splatting use for example {3, 5}. Default is {3}.
mode	ENUM PointCloud.toImageMode	If several points in the pointcloud splat onto the same pixel, it must be choosen if the TOPMOST or BOTTOMMOST value is written to the result pixel. Default is TOPMOST.
generateIntensity	BOOL	Select if an intensity image is to be generated also from the intensity part of the pointcloud. Defaults to true.

Return values
Name	Type	Description
rangeImage	OBJECT Image	Output range image of UINT16 type.
intensityImage	OBJECT Image	Intensity image of UINT8 type, if generated.

Sample

rangeImageReference, intensityImage = PointCloud.toImage(pointcloud, boundingBox, {0.2})

toImageInplace()

Short description

Create a range image from a pointcloud. The image is formed by projection of the point in the point cloud onto the plane with normal (0, 0, 1). The x and y axes of the point cloud are aligned with the x and y axes of the resulting image. The employed method is sometimes referred to as splatting, i.e., each point in the pointcloud is splatted onto the plane, writing its z-distance to an splat area given in pixels. Pixels which are not hit by any splats are marked as missing data. If such holes appear in the generated image try increasing the splat sizes, make the pixel sizes larger or use methods to fill missing data. The operation is performed inplace for the input image, that is, the content of image will change inside the function. The function returns two images, one with the z-distance in each pixel and one with the intensity value from the pointcloud. Supported rangeImageReference types are unsigned integer images, i.e., UINT8, UINT16, UINT32 and UINT64. Image world coordinate system handling: The input image defines the world coordinate system and this image is updated and returned inplace. Make sure to set pixel sizes and origin to appropriate values before calling this function to achieve the desired result. Missing data handling: Pixels in the output range image and intensity image will be zero (missing data) if no point in the pointcloud had effect over that pixel. Missing data can be reduced by increasing the splat sizes or by post processing.

Keywords

convert, heightmap, project, splat

See also

Image.toPointCloud

Parameters
Name	Type	Description
pointcloud	CONST_OBJECT PointCloud	The input pointcloud
rangeImageReference	OBJECT Image	Both input and output image into which to render the result. Make sure to set pixel sizes and origin of this image to appropriate values before calling this function to achieve the desired result.
splatSizes	INT	Optional vector of splat kernel sizes in the x and y dimensions. To select a splat size of 5 use {5}, for anisotropic splatting use for example {3, 5}. Default is {3}.
mode	ENUM PointCloud.toImageMode	If several points in the pointcloud splat onto the same pixel, it must be choosen if the TOPMOST or BOTTOMMOST value is written to the result pixel. Default is true.
includeIntensity	BOOL	Select if an intensity image should also be generated. Defaults to true.

Return values
Name	Type	Description
rangeImageReference	OBJECT Image	Reference to the output range image.
intensityImage	OBJECT Image	The resulting intensity image, if generated.

Sample

rangeImageReference, intensityImage = PointCloud.toImageInplace(pointcloud, rangeImageReference, {3}, "TOPMOST", true)

toPoints()

Short description

Returns the 3D coordinates of all points in the point cloud as vector of Point objects and the intensities as vector of float values.

Parameters
Name	Type	Description
inputCloud	CONST_OBJECT PointCloud	Point cloud to get the points from

Return values
Name	Type	Description
points	OBJECT Point	3D coordinates as vector of Point objects.
intensities	FLOAT	Intensities as vector of float values

Sample

local points, intensities = PointCloud.toPoints(inputCloud)

toString()

Short description

Gets a user-friendly string description of the point cloud, containing important properties.

Parameters
Name	Type	Description
inputCloud	CONST_OBJECT PointCloud	The point cloud to describe.

Return values
Name	Type	Description
str	STRING	User-friendly description of the point cloud.

Sample

str = PointCloud.toString(inputCloud)

toVector()

Short description

Returns the x, y, z and intensity value of all points in the point cloud as vectors of float values.

Parameters
Name	Type	Description
inputCloud	CONST_OBJECT PointCloud	Point cloud to get the points from

Return values
Name	Type	Description
x	FLOAT	X values in [mm]
y	FLOAT	Y values in [mm]
z	FLOAT	Z values in [mm]
intensity	FLOAT	Intensity values

Sample

local x,y,z,intensity = PointCloud.toVector(inputCloud)

transform()

Short description

Transform a point cloud. Fails if the transform is not a 3D transform.

See also

Parameters
Name	Type	Description
inputCloud	CONST_OBJECT PointCloud	The input point cloud.
transform	CONST_OBJECT Transform	Transform to apply.

Return values
Name	Type	Description
transformedCloud	OBJECT PointCloud	Transformed point cloud or nil on error

Sample

local transformedCloud = PointCloud.transform(inputCloud, transform)

transformInplace()

Short description

In-place version of the PointCloud.transform function that modifies the input point cloud. See base function for full documentation.

See also

PointCloud.transform

Parameters
Name	Type	Description
inputCloud	OBJECT PointCloud	The input point cloud. This point cloud is overwritten with the transformed point cloud.
transform	CONST_OBJECT Transform	Transform to apply.

Return values
Name	Type	Description
result	OBJECT PointCloud	Reference to the result point cloud or nil on error.

Sample

local result = PointCloud.transformInplace(inputCloud, transform)

PointCloud.Matching

Short description

Point cloud matching algorithms

Overview

PointCloud.Matching.Halcon

Short description

Point cloud matching algorithms based on Halcon

Overview

PointCloud.Matching.Halcon.SurfaceMatcher

Short description

Implements surface-based matching from Halcon. See operator create_surface_model for additional information. The surface model is created by resampling a teach object with a certain distance. The teach object can be either a PointCloud with additional normal information provided by a n by 4 Matrix or a Mesh. The sampling distance must be specified in the parameter relativeSamplingDistance and is parametrized relative to the diameter of the axis-parallel bounding box of the teach object. For example, if relativeSamplingDistance is set to 0.05 and the diameter of model is 100 mm, the points sampled from the object’s surface will be approximately 5 mm apart. The sampled points are used for the approximate matching in the match() call. Note that outlier points in the teach model should be avoided, as they would corrupt the diameter. Reducing relativeSamplingDistance leads to more points, and in turn to a more stable but slower matching. Increasing relativeSamplingDistance leads to fewer points, and in turn to a less stable but faster matching. The sampled points are used for finding the object model in a scene during a match() call. For this, all possible pairs of points from the point set are examined, and the distance and relative surface orientation of each pair is computed. Both values are discretized and stored for matching. The teach model is resampled a second time for the pose refinement. The second sampling is done with a smaller sampling distance, leading to more points. The parameter relativePoseRefinementSamplingDistance sets the sampling distance relative to the object’s diameter. Decreasing the value results in a more accurate pose refinement but a larger model and a slower model generation and matching. Increasing the value leads to a less accurate pose refinement but a smaller model and faster model generation and matching. See Halcon’s operator find_surface_model for additional information. A minimum usage example is: local matcher = PointCloud.Matching.Halcon.SurfaceMatcher.create() local teachObject = matcher:teachMesh(teachMesh, 0.02) local scores, poses = PointCloud.Matching.Halcon.SurfaceMatcher.match(matcher, pointCloud) for index, score in ipairs(scores) do print(score, poses[index]:toString()) — transform the resampled teach model into the scene local teachObjectTransformed = teachObject:transform(poses[index]) end

Detailed description

The surface model is created by resampling a teach object with a certain distance. The teach object can be either a PointCloud with additional normal information provided by a n by 4 Matrix or a Mesh. The sampling distance must be specified in the parameter relativeSamplingDistance and is parametrized relative to the diameter of the axis-parallel bounding box of the teach object. For example, if relativeSamplingDistance is set to 0.05 and the diameter of model is 100 mm, the points sampled from the object’s surface will be approximately 5 mm apart. The sampled points are used for the approximate matching in the match() call. Note that outlier points in the teach model should be avoided, as they would corrupt the diameter. Reducing relativeSamplingDistance leads to more points, and in turn to a more stable but slower matching. Increasing relativeSamplingDistance leads to fewer points, and in turn to a less stable but faster matching.

The sampled points are used for finding the object model in a scene during a match() call. For this, all possible pairs of points from the point set are examined, and the distance and relative surface orientation of each pair is computed. Both values are discretized and stored for matching.

The teach model is resampled a second time for the pose refinement. The second sampling is done with a smaller sampling distance, leading to more points. The parameter relativePoseRefinementSamplingDistance sets the sampling distance relative to the object’s diameter. Decreasing the value results in a more accurate pose refinement but a larger model and a slower model generation and matching. Increasing the value leads to a less accurate pose refinement but a smaller model and faster model generation and matching. See Halcons operator find_surface_model for additional information.

A minimum usage example is:

local matcher = PointCloud.Matching.Halcon.SurfaceMatcher.create()
local teachObject = matcher:teachMesh(teachMesh, 0.02)
local scores, poses = PointCloud.Matching.Halcon.SurfaceMatcher.match(matcher, pointCloud)
for index, score in ipairs(scores) do
  print(score, poses[index]:toString())
  -- transform the resampled teach model into the scene
  local teachObjectTransformed = teachObject:transform(poses[index])
end

Overview

create(), getKeypointFraction(), getMaxMatches(), getMinScore(), getMinSeparation(), getNormalComputationMethod(), getPoseRefinementParameters(), getRelativeSamplingDistance(), match(), setKeypointFraction(), setMaxMatches(), setMinScore(), setMinSeparation(), setNormalComputationMethod(), setPoseRefinementParameters(), setRelativeSamplingDistance(), teachMesh(), teachPointCloud()

Functions

create()

Short description

Create a handle for the surface-based matching.

Return values
Name	Type	Description
matcher	HANDLE	Handle for matcher.

Sample

local matcher = PointCloud.Matching.Halcon.SurfaceMatcher.create()

getKeypointFraction()

Short description

Get the fraction of sampled scene points used as key points.

Parameters
Name	Type	Description
matcher	HANDLE	Handle for matcher.

Return values
Name	Type	Description
keypointFraction	FLOAT	fraction of sampled scene points used as key points.

Sample

local keypointFraction = PointCloud.Matching.Halcon.SurfaceMatcher.getKeypointFraction(matcher)

getMaxMatches()

Short description

Gets the maximum number of matches that are returned.

Parameters
Name	Type	Description
matcher	HANDLE	Handle for matcher.

Return values
Name	Type	Description
maxMatches	INT	The maximum number of matches.

Sample

local maxMatches = PointCloud.Matching.Halcon.SurfaceMatcher.getMaxMatches(matcher)

getMinScore()

Short description

Get the minimum score. The score is the relative number of sampled model points found in the matching. A model point is defined to be found if there is a scene point close to it.

Parameters
Name	Type	Description
matcher	HANDLE	Handle for matcher.

Return values
Name	Type	Description
minimumScore	FLOAT	Minimum score of the found matchings.

Sample

local minimumScore = PointCloud.Matching.Halcon.SurfaceMatcher.getMinScore(matcher)

getMinSeparation()

Short description

Get the minimum relative overlap distance between matches.

Parameters
Name	Type	Description
matcher	HANDLE	Handle for matcher.

Return values
Name	Type	Description
overlapDistance	FLOAT	Minimum relative overlap distance between matches.

Sample

local overlapDistance = PointCloud.Matching.Halcon.SurfaceMatcher.getMinSeparation(matcher)

getNormalComputationMethod()

Short description

Get the normal computation method

Parameters
Name	Type	Description
matcher	HANDLE	Handle for matcher.

Return values
Name	Type	Description
type	ENUM NormalComputationMethod	Normal computation method

Sample

local type = PointCloud.Matching.Halcon.SurfaceMatcher.getNormalComputationMethod(matcher)

getPoseRefinementParameters()

Short description

Get parameters related to the dense pose refinement.

Parameters
Name	Type	Description
matcher	HANDLE	Handle for matcher.

Return values
Name	Type	Description
relativeDistanceThreshold	FLOAT	Distance threshold for dense pose refinement relative to the diameter of the surface model.
relativeScoringThreshold	FLOAT	Distance threshold for scoring relative to the diameter of the surface model.

Sample

local relativeDistanceThreshold, relativeScoringThreshold = PointCloud.Matching.Halcon.SurfaceMatcher.getPoseRefinementParameters(matcher)

getRelativeSamplingDistance()

Short description

Get the relative sampling distance for the point cloud input during matching.

Parameters
Name	Type	Description
matcher	HANDLE	Handle for matcher.

Return values
Name	Type	Description
relativeSamplingDistance	FLOAT	Sampling distance relative to the diameter of point cloud input during matching.

Sample

local relativeSamplingDistance = PointCloud.Matching.Halcon.SurfaceMatcher.getRelativeSamplingDistance(matcher)

match()

Short description

Perform the matching of the teach object in the point cloud: The matching is divided into three steps: 1.) Approximate matching: The approximate poses of the instances of the surface model in the scene are searched. 2.) Sparse pose refinement: In this second step, the approximate poses found in the previous step are further refined. This increases the accuracy of the poses and the significance of the score value. The sparse pose refinement uses the sampled scene points from the approximate matching. The pose is optimized such that the distances from the sampled scene points to the plane of the closest model point are minimal. The plane of each model point is defined as the plane perpendicular to its normal. 3.) Dense pose refinement: Accurately refines the poses found in the previous steps. This step works similar to the sparse pose refinement and minimizes the distances between the scene points and the planes of the closest model points.

Detailed description

The matching is divided into three steps:

Approximate matching: The approximate poses of the instances of the surface model in the scene are searched.
Sparse pose refinement: In this second step, the approximate poses found in the previous step are further refined. This increases the accuracy of the poses and the significance of the score value. The sparse pose refinement uses the sampled scene points from the approximate matching. The pose is optimized such that the distances from the sampled scene points to the plane of the closest model point are minimal. The plane of each model point is defined as the plane perpendicular to its normal.
Dense pose refinement: Accurately refines the poses found in the previous steps. This step works similar to the sparse pose refinement and minimizes the distances between the scene points and the planes of the closest model points.

Parameters
Name	Type	Description
matcher	HANDLE	Handle for matcher.
pointCloud	CONST_OBJECT PointCloud	The point cloud for matching.

Return values
Name	Type	Description
score	FLOAT	The score is between 0 and 1. Relative number of sampled model points found in the matching. A model point is defined to be found if there is a scene point close to it.
pose	OBJECT Transform	The pose for the teach object in the matching result.

Sample

local score, pose = PointCloud.Matching.Halcon.SurfaceMatcher.match(matcher, pointCloud)

setKeypointFraction()

Short description

Set the fraction of sampled scene points used as key points. A set of key points is selected from the sampled scene points. The number of selected key points is controlled with the parameter keypointFraction. Increasing keypointFraction means that more key points are selected from the scene, resulting in a slower but more stable matching.

Parameters
Name	Type	Description
matcher	HANDLE	Handle for matcher.
keypointFraction	FLOAT	Fraction of sampled scene points used as key points. Must be between 0 and 1. Default is 0.2.

Return values
Name	Type	Description
success	BOOL	True on success, false if parameters where invalid.

Sample

local success = PointCloud.Matching.Halcon.SurfaceMatcher.setKeypointFraction(matcher, keypointFraction)

setMaxMatches()

Short description

Sets the maximum number of matches that are returned.

Parameters
Name	Type	Description
matcher	HANDLE	Handle for matcher.
maxMatches	INT	The maximum number of matches. Must be larger than 0. Default is 1.

Return values
Name	Type	Description
success	BOOL	True on success, false if parameters where invalid.

Sample

local success = PointCloud.Matching.Halcon.SurfaceMatcher.setMaxMatches(matcher, maxMatches)

setMinScore()

Short description

Set the minimum score. The score is the relative number of sampled model points found in the matching. A model point is defined to be found if there is a scene point close to it.

Parameters
Name	Type	Description
matcher	HANDLE	Handle for matcher.
minimumScore	FLOAT	Minimum score of the found matchings. Must be positive. Default is 0.

Return values
Name	Type	Description
success	BOOL	True on success, false if parameters where invalid.

Sample

local success = PointCloud.Matching.Halcon.SurfaceMatcher.setMinScore(matcher, minimumScore)

setMinSeparation()

Short description

Set the minimum relative overlap distance between matches. The distance is computed as the diference between the matches axis-aligned bounding boxes.

Parameters
Name	Type	Description
matcher	HANDLE	Handle for matcher.
overlapDistance	FLOAT	Minimum relative overlap distance between matches. Must be non-negative. Default is 0.5.

Return values
Name	Type	Description
success	BOOL	True on success, false if parameters where invalid.

Sample

local success = PointCloud.Matching.Halcon.SurfaceMatcher.setMinSeparation(matcher, overlapDistance)

setNormalComputationMethod()

Short description

Set the normal computation method

Parameters
Name	Type	Description
matcher	HANDLE	Handle for matcher.
type	ENUM NormalComputationMethod	Normal computation method. Default is 'FAST'.

Return values
Name	Type	Description
success	BOOL	True on success, false if parameters where invalid.

Sample

local success = PointCloud.Matching.Halcon.SurfaceMatcher.setNormalComputationMethod(matcher, type)

setPoseRefinementParameters()

Short description

Set parameters related to the dense pose refinement.

Parameters
Name	Type	Description
matcher	HANDLE	Handle for matcher.
relativeDistanceThreshold	FLOAT	Distance threshold for dense pose refinement relative to the diameter of the surface model. Only scene points that are closer to the object than this distance are used for the optimization. Must be larger than zero. Default is 0.005.
relativeScoringThreshold	FLOAT	Distance threshold for scoring relative to the diameter of the surface model. Only scene points that are closer to the object than this distance are considered to be 'on the model' when computing the score after the pose refinement. Must be larger than zero. Default is 0.05.

Return values
Name	Type	Description
success	BOOL	True on success, false if parameters where invalid.

Sample

local success = PointCloud.Matching.Halcon.SurfaceMatcher.setPoseRefinementParameters(matcher, relativeDistanceThreshold, relativeScoringThreshold)

setRelativeSamplingDistance()

Short description

Set the relative sampling distance for the point cloud input during matching.

Parameters
Name	Type	Description
matcher	HANDLE	Handle for matcher.
relativeSamplingDistance	FLOAT	Sampling distance relative to the diameter of point cloud input during matching. Must be between 0 and 1. Default is 0.05.

Return values
Name	Type	Description
success	BOOL	True on success, false if parameters where invalid.

Sample

local success = PointCloud.Matching.Halcon.SurfaceMatcher.setRelativeSamplingDistance(matcher, relativeSamplingDistance)

teachMesh()

Short description

Teach a model for matching from a mesh object.

Parameters
Name	Type	Description
matcher	HANDLE	Handle for matcher.
mesh	CONST_OBJECT Mesh	Mesh representing the teach object.
relativeSamplingDistance	FLOAT	Sampling distance relative to axis-parallel bounding box used for sampling the teach model.
relativePoseRefinementSamplingDistance	FLOAT	Set the sampling distance for the pose refinement relative to the teach object’s diameter. Decreasing this value leads to a more accurate pose refinement but a larger model and slower model generation and refinement. Increasing the value leads to a less accurate pose refinement but a smaller model and faster model generation and matching. Default is 0.01.

Return values
Name	Type	Description
sampledTeachObject	OBJECT PointCloud	The resampled point cloud that is used for the approximate matching in the match() call.

Sample

local teachObject = PointCloud.Matching.Halcon.SurfaceMatcher.teachMesh(matcher, mesh, relativeSamplingDistance, relativePoseRefinementSamplingDistance)

teachPointCloud()

Short description

Teach a model for matching from a point cloud and normal information.

Parameters
Name	Type	Description
matcher	HANDLE	Handle for matcher.
pointCloud	CONST_OBJECT PointCloud	Point cloud with n points representing the teach object.
normals	CONST_OBJECT Matrix	The normals represented as n x 4 matrix.
relativeSamplingDistance	FLOAT	Sampling distance relative to axis-parallel bounding box used for sampling the teach model.
relativePoseRefinementSamplingDistance	FLOAT	Set the sampling distance for the pose refinement relative to the teach object’s diameter. Decreasing this value leads to a more accurate pose refinement but a larger model and slower model generation and refinement. Increasing the value leads to a less accurate pose refinement but a smaller model and faster model generation and matching. Default is 0.01.

Return values
Name	Type	Description
sampledTeachObject	OBJECT PointCloud	The resampled point cloud that is used for the approximate matching in the match() call.

Sample

local teachObject = PointCloud.Matching.Halcon.SurfaceMatcher.teachPointCloud(matcher, pointCloud, normals, relativeSamplingDistance, relativePoseRefinementSamplingDistance)

PointCloud.RangeFilter

Short description

Removes points outside of the defined attribute range (or inside, if the behavior is inverted with setNegative(true)). By default, the filter does not remove any points.

Overview

create(), filter(), setIntensityRange(), setNegative(), setXRange(), setYRange(), setZRange()

Functions

create()

Short description

Create a new instance.

Return values
Name	Type	Description
handle	HANDLE	Handle to the new instance

Sample

local handle = PointCloud.RangeFilter.create()

filter()

Short description

Return the area filtered PointCloud.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
inputCloud	CONST_OBJECT PointCloud	The PointCloud object which is filtered

Return values
Name	Type	Description
filteredCloud	OBJECT PointCloud	The area filtered PointCloud

Sample

local areaCloud = PointCloud.RangeFilter.filter(handle, cloud)

setIntensityRange()

Short description

Set the filter range for intensity values. Points outside of this range are filtered out. If both parameters are 0 (default), the filter is disabled.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
minIntensity	FLOAT	Minimum intensity value in range [0.0-1.0]
maxIntensity	FLOAT	Maximum intensity value in range [0.0-1.0]

Sample

PointCloud.RangeFilter.setIntensityRange(handle, 0.8, 1.0)

setNegative()

Short description

Set to true to invert the filter behavior (return points outside of range).

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
behavior	BOOL	Invert filter behavior, default is false

Sample

PointCloud.RangeFilter.setNegative(handle, true)

setXRange()

Short description

Set the filter range in x-direction. Points outside of this range are filtered out. If both parameters are 0 (default), the filter is disabled.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
minX	FLOAT	Minimum x value
maxX	FLOAT	Maximum x value

Sample

PointCloud.RangeFilter.setXRange(handle, -10.5, 15.0)

setYRange()

Short description

Set the filter range in y-direction. Points outside of this range are filtered out. If both parameters are 0 (default), the filter is disabled.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
minY	FLOAT	Minimum y value
maxY	FLOAT	Maximum y value

Sample

PointCloud.RangeFilter.setYRange(handle, -10.5, 15.0)

setZRange()

Short description

Set the filter range in z-direction. Points outside of this range are filtered out. If both parameters are 0 (default), the filter is disabled.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
minZ	FLOAT	Minimum z value
maxZ	FLOAT	Maximum z value

Sample

PointCloud.RangeFilter.setZRange(handle, -10.5, 15.0)

Profile

Short description

A data type for vector of 1D measurements. Three main components of the data type are - A vector of measurement values represented in 32 bit float precision. - An optional vector of valid flags indicating if the measurement value at the same index is valid. An integer representation is used where 0 means invalid and 1 means valid measurement. A global flag indicates if algorithms must consider the valid flags vector at all in computations. - Coordinate information for each measurement value, relating the measurement to a world position (temporal or spatial). The main purpose of the Profile type is for 1D processing, e.g., filtering finding peaks and edges, analyze trends, matching 1D patterns etc. Processing is done on the measurement vector, taking the valid flag vector into account if enabled. The purpose of the coordinate vector is to relate the measurements with a world position. The world position can be both temporal or spatial, e.g., time, angle or 2D (x,y) position. The following three examples illustrate possible use cases for the Profile type: Example 1: The measurement values represent the number of sent packages in a logistics center each day. The coordinate information represents time (day) and the valid flags vector if there was a valid package count on the corresponding day. Example 2: The measurements are range values from a LiDAR scan in polar format. The coordinate is the angle for each range measurement. The valid flag vector indicates whether the corresponding range value is valid, e.g., if there was a reliable "echo" received. Example 3: The measurement values are the height values sampled evenly along a straight line in a heightmap image. The coordinate vector in this case is a (x,y) world coordinate in millimeters or pixels, where each height value was sampled. As heightmaps can contain missing data pixels (no height value available), the valid flag vector carries this information. The coordinate information can be represented in different ways: An implicit representation stores a start coordinate (1D float value or 2D point) and a constant delta (1D float value or 2D vector). An explicit representation stores the coordinate (1D float value or 2D point) in a vector of the same length as the measurement vector. How the coordinate information is represented is determined when the Profile object is created. There is also a 'isClosed'-flag indicating if the coordinates wraps around so that the first and last samples are neighbors. This can happen for example for a 360 degree LiDAR scan or if one samples height values from a circle in a heightmap. This has effect in certain filtering operations where neighboring samples are considered to produce an output.

Keywords

1d, array, scan, vector

Overview

abs(), absInplace(), add(), addConstant(), addConstantInplace(), addInplace(), addNoise(), addNoiseInplace(), aggregate(), binarize(), binarizeInplace(), blur(), centralDifference(), clamp(), clampInplace(), clone(), concatenate(), concatenateInplace(), convertCoordinateType(), convolve(), create(), createFromPoints(), createFromVector(), crop(), difference(), differenceInplace(), divide(), divideInplace(), fillInvalidValues(), fillInvalidValuesWithReference(), findEqual(), findLocalExtrema(), findRangeEdges(), fourierTransform(), fourierTransformInverse(), gauss(), gaussDerivative(), getArea(), getClosed(), getCoordinate(), getCoordinateType(), getDistance(), getHistogram(), getIntersectionAngle(), getMax(), getMean(), getMedian(), getMin(), getSize(), getStandardDeviation(), getSum(), getValidCount(), getValidFlag(), getValidFlagsEnabled(), getValue(), interpolateCoordinate(), load(), median(), mirror(), mirrorInplace(), multiply(), multiplyAddConstant(), multiplyAddConstantInplace(), multiplyConstant(), multiplyConstantInplace(), multiplyInplace(), pow(), powInplace(), removeValidFlagVector(), resize(), resizeScale(), rotate(), rotateInplace(), save(), setClosed(), setCoordinate(), setImplicitCoordinates(), setValidFlag(), setValidFlagRange(), setValidFlagsEnabled(), setValue(), shrink(), shrinkInplace(), sort(), subtract(), subtractInplace(), threshold(), toImage(), toString(), toVector(), translate(), translateInplace()

Functions

abs()

Short description

Computes the absolute value of each measurement in the profile. Coordinate system handling: The coordinate representation of the input profile is copied to the output profile. Valid flags handling: The valid flags representation of the input profile is copied to the output profile.

Keywords

absolute

See also

Profile.absInplace

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The source profile.

Return values
Name	Type	Description
result	OBJECT Profile	The resulting profile.

Sample

local result = Profile.abs(profile)

absInplace()

Short description

In-place version of the Profile.abs function that modifies the input profile. See base function for full documentation.

Keywords

absolute

See also

Profile.abs

Parameters
Name	Type	Description
profile	OBJECT Profile	The source profile. This profile is overwritten with the result of the abs.

Return values
Name	Type	Description
result	OBJECT Profile	Reference to the result profile.

Sample

local result = Profile.absInplace(profile)

add()

Short description

Adds two profiles sample-wise. The two profiles must have the same number of measurements. Coordinate system handling: The coordinate representation of the first input profile is copied to the output profile. Valid flags handling: Both input profiles must have a valid measurement to produce a valid output for an index.

Keywords

plus

See also

Profile.addConstant, Profile.addInplace

Parameters
Name	Type	Description
profile1	CONST_OBJECT Profile	The first source profile.
profile2	CONST_OBJECT Profile	The second source profile.

Return values
Name	Type	Description
result	OBJECT Profile	The resulting profile.

Sample

local result = Profile.add(profile1, profile2)

addConstant()

Short description

Adds a constant to the measurements of the profile. Coordinate system handling: The coordinate representation of the input profile is copied to the output profile. Valid flags handling: The valid flags representation of the input profile is copied to the output profile.

Keywords

translate, shift

See also

Profile.addConstantInplace

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The source profile.
constant	FLOAT	The constant to add.

Return values
Name	Type	Description
result	OBJECT Profile	The resulting profile.

Sample

local result = Profile.addConstant(profile, constant)

addConstantInplace()

Short description

In-place version of the Profile.addConstant function that modifies the input profile. See base function for full documentation.

Keywords

translate, shift

See also

Profile.addConstant

Parameters
Name	Type	Description
profile	OBJECT Profile	The source profile. This profile is overwritten with the result of the sum.
constant	FLOAT	The constant to add.

Return values
Name	Type	Description
result	OBJECT Profile	Reference to the result profile.

Sample

local result = Profile.addConstantInplace(profile, constant)

addInplace()

Short description

In-place version of the Profile.add function that modifies the input profile. See base function for full documentation.

Keywords

plus

See also

Profile.addConstantInplace, Profile.add

Parameters
Name	Type	Description
profile1	OBJECT Profile	The first source profile. This profile is overwritten with the result of the sum.
profile2	CONST_OBJECT Profile	The second source profile.

Return values
Name	Type	Description
result	OBJECT Profile	Reference to the result profile.

Sample

local result = Profile.addInplace(profile1, profile2)

addNoise()

Short description

Adds noise to profile values. Noise with normal or uniform distribution can be selected. noiseType NORMAL: param1: standard deviation. param2: mean. noiseType UNIFORM: param1: Minimum value. param2: Maximum value.

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The source profile.
noiseType	ENUM NoiseType	Distribution of noise. NORMAL or UNIFORM.
param1	FLOAT	Standard deviation if noiseType NORMAL (Default value 1.0). Min value if noiseType UNIFORM (Default value -1.0).
param2	FLOAT	Mean value if noiseType NORMAL (Default value 0.0). Max value if noiseType UNIFORM (Default value 1.0).
randSeed	INT	Random seed, optional. No new seed is set if negative. Default: 0

Return values
Name	Type	Description
result	OBJECT Profile	Profile with noise added.

Sample

local result = Profile.addNoise(profile, noiseType, param1, param2, randSeed)

addNoiseInplace()

Short description

In-place version of addNoise. See base function for full documentation.

Parameters
Name	Type	Description
profile	OBJECT Profile	The profile to add noise to.
noiseType	ENUM NoiseType	Distribution of noise. NORMAL or UNIFORM.
param1	FLOAT	Standard deviation if noiseType NORMAL (Default value 1.0). Min value if noiseType UNIFORM (Default value -1.0).
param2	FLOAT	Mean value if noiseType NORMAL (Default value 0.0). Max value if noiseType UNIFORM (Default value 1.0).
randSeed	INT	Random seed, optional. No new seed is set if negative. Default: 0

Return values
Name	Type	Description
result	OBJECT Profile	Reference to the profile with noise added.

Sample

local result = Profile.addNoiseInplace(profile, noiseType, param1, param2, randSeed)

aggregate()

Short description

Aggregate a set of profiles into one profile. Different aggregation operations are available such as sum, mean, min, max and median. All profiles must have the same number of measurements. All or none of the profiles must use the valid data flags. Coordinate system handling: The coordinate representation of the first input profile is copied to the output profile. Valid flags handling: Invalid values are excluded from the aggregation, e.g. the mean value is the mean of the valid values at a given position in the profiles. If no profile has a valid value at a particular index, the output profile will have an invalid value at that index. A profile containing the number of valid samples used in the aggregation at each index is returned. If no profile has invalid values, the valid samples profile will be constant and equal to the number of input profiles.

Keywords

max, mean, median, min, sum

Parameters
Name	Type	Description
profiles	CONST_OBJECT Profile	The source profiles.
operation	ENUM AggregateOperation	The type of operation used to generate the aggregate.

Return values
Name	Type	Description
aggregateProfile	OBJECT Profile	The aggregated profile.
validValuesProfile	OBJECT Profile	The number of entries used for each aggregated sample.

Sample

local aggregateProfile, validValuesProfile = Profile.aggregate(profiles, operation)

binarize()

Short description

Applies a threshold interval (lowerThreshold, upperThreshold) to the profile to create a binary profile. Measurement values outside the interval have the value 0 in the output profile, and values within the interval have a user-specified value. Coordinate system handling: The coordinate representation is not considered in this operation. Valid flags handling: If a measurement is invalid in the input profile it is invalid in the output profile.

Keywords

threshold

See also

Profile.binarizeInplace

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The source profile.
lowerThreshold	FLOAT	Lower threshold for the binarization.
upperThreshold	FLOAT	Upper threshold for the binarization.
outputValue	FLOAT	Value assigned to the measurements within the threshold interval. Optional, default value is 1.

Return values
Name	Type	Description
binarizedProfile	OBJECT Profile	Binarized profile.

Sample

local binarizedProfile = Profile.binarize(profile, lowerThreshold, upperThreshold, outputValue)

binarizeInplace()

Short description

In-place version of the Profile.binarize function that modifies the input profile. See base function for full documentation.

Keywords

threshold

See also

Profile.binarize

Parameters
Name	Type	Description
profile	OBJECT Profile	The source profile. This profile is overwritten with the binarized result.
lowerThreshold	FLOAT	Lower threshold for the binarization.
upperThreshold	FLOAT	Upper threshold for the binarization.
outputValue	FLOAT	Value assigned to the measurements within the threshold interval. Optional, default value is 1.

Return values
Name	Type	Description
binarizedProfile	OBJECT Profile	Reference to the result profile.

Sample

local binarizedProfile = Profile.binarizeInplace(profile, lowerThreshold, upperThreshold, outputValue)

blur()

Short description

Smooths a profile using a constant normalized box filter kernel of the given size. Coordinate system handling: The coordinate representation is not considered in this operation. The filter operation wraps around if the isClosed-flag is on. Valid flags handling: Only the valid measurements are considered in the calculation. By default, all invalid measurements will be marked as invalid also in the output. If the fill flag is set to true, invalid measurements will be filled with filtered neighbor values where possible.

Keywords

box, filter, gauss, low pass, lp, smooth

See also

Profile.median, Profile.gauss

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	Input profile.
kernelSize	INT	Size of the kernel, must be positive, odd and smaller than the profile length.
fillInvalid	BOOL	Optional flag to also fill in invalid values while filtering. Default is false.

Return values
Name	Type	Description
smoothProfile	OBJECT Profile	Output profile, smoothed by the blur filter.

Sample

local smoothProfile = Profile.blur(profile, kernelSize)

centralDifference()

Short description

Differentiate a profile using a first- or second-order central finite difference filter kernel. A step parameter determines how far from the center the difference is taken: First order difference: Step 1: [1 0 -1] Step 2: [1 0 0 0 -1] and so on. Second order difference: Step 1: [1 -2 1] Step 2: [1 0 -2 0 1] and so on. The output is set to zero in the beginning and end of the output profile, where the entire filter does not fit within the profile. Coordinate system handling: The coordinate representation is not considered in this operation. The filter operation wraps around if the isClosed-flag is on. Valid flags handling: If the valid data flags are enabled, the output is set as invalid if any non-zero filter coefficient hits an invalid input value or is out of bounds. For example, if differenceStep=1, the first and last output values is always set as invalid, since the 1 and -1 filter coefficients are out of bounds of the input profile.

Keywords

first, gradient, second, slope, derivative

See also

Profile.gaussDerivative

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	Input profile.
differenceStep	INT	How far from the center the kernel weights are placed, must be strictly positive.
order	ENUM DifferentiationOrder	FIRST gives first order derivative and SECOND gives second order derivative.

Return values
Name	Type	Description
diffProfile	OBJECT Profile	Output profile created by the central difference filter.

Sample

local diffProfile = Profile.centralDifference(profile, differenceStep, order)

clamp()

Short description

Clamps each measurement value to an interval (minValue, maxValue). Coordinate system handling: The coordinate representation of the input profile is copied to the output profile. Valid flags handling: The valid flags representation of the input profile is copied to the output profile.

Keywords

threshold, limit

See also

Profile.shrink, Profile.clampInplace

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The source profile.
minValue	FLOAT	The minimum value to clamp to.
maxValue	FLOAT	The maximum value to clamp to.

Return values
Name	Type	Description
result	OBJECT Profile	The clamped profile.

Sample

local result = Profile.clamp(profile, minValue, maxValue)

clampInplace()

Short description

In-place version of the Profile.clamp function that modifies the input profile. See base function for full documentation.

Keywords

threshold, limit

See also

Profile.shrinkInplace, Profile.clamp

Parameters
Name	Type	Description
profile	OBJECT Profile	The source profile. This profile is overwritten with the clapped result.
minValue	FLOAT	The minimum value to clamp to.
maxValue	FLOAT	The maximum value to clamp to.

Return values
Name	Type	Description
result	OBJECT Profile	Reference to the result profile.

Sample

local result = Profile.clampInplace(profile, minValue, maxValue)

clone()

Short description

Creates an independent copy of a profile.

Keywords

copy

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	Input profile.

Return values
Name	Type	Description
clonedProfile	OBJECT Profile	Copy of the input profile.

Sample

local clonedProfile = Profile.clone(profile)

concatenate()

Short description

Concatenates two profiles. The profiles must have the same coordinate type. Periodic flag and implicit coordinates are copied from the first profile. If any of the two profiles uses valid flags the result also does so.

Keywords

merge, join

See also

Profile.concatenateInplace

Parameters
Name	Type	Description
profile1	CONST_OBJECT Profile	The source profile 1.
profile2	CONST_OBJECT Profile	The source profile 2.

Return values
Name	Type	Description
result	OBJECT Profile	Concatenated profile.

Sample

local result = Profile.concatenate(profile1, profile2)

concatenateInplace()

Short description

In-place version of concatenate that modifies the first input profile. See base function for full documentation.

Keywords

merge, join

See also

Profile.concatenate

Parameters
Name	Type	Description
profile1	OBJECT Profile	The source profile 1 and result profile.
profile2	CONST_OBJECT Profile	The source profile 2.

Return values
Name	Type	Description
result	OBJECT Profile	Reference to the concatenated profile.

Sample

local result = Profile.concatenateInplace(profile1, profile2)

convertCoordinateType()

Short description

Converts sample coordinates in the profile. Possible coordinate types: IMPLICIT_1D, EXPLICIT_1D, IMPLICIT_2D, EXPLICIT_2D. Note that the values in the profile are kept unchanged. Implicit to explicit: Change the coordinate representation from start + delta representation, to vector with absolute positions. Explicit to implicit: Change the coordinate representation from vector with absolute coordinates, to a start + delta representation. Preserving the coordinates for the first and last sample. 1D to 2D: The 1D coordinates are placed on the x-axis in the 2D coordinates. 2D to 1D: The accumulated curve length in 2D is used as the new 1D coordinates. Thus, start position is 0.0.

Parameters
Name	Type	Description
profile	OBJECT Profile	The profile object.
coordinateType	ENUM CoordinateType	New coordinate type.

Return values
Name	Type	Description
result	OBJECT Profile	Reference to the result profile.

Sample

 local result = Profile.convertCoordinateType(profile, coordinateType)

convolve()

Short description

Convolves a profile with a given filter kernel. Coordinate system handling: The coordinate representation is not considered in this operation. The filter operation wraps around if the isClosed-flag is on. Valid flags handling: Invalid flags are not allowed in this operation.

Keywords

filter

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	Input profile.
kernel	FLOAT	Filter kernel. Must be shorter than the profile.

Return values
Name	Type	Description
filteredProfile	OBJECT Profile	Output profile, filtered with the kernel.

Sample

local filteredProfile = Profile.convolve(profile, kernel)

create()

Short description

Creates a new Profile object with all measurements set to a constant value. Coordinate system handling: The coordinate representation will be implicit 1D, starting at 0 with a delta value of 1. Valid flags handling: All measurements are considered as valid. No valid flags vector is created.

See also

Profile.clone

Parameters
Name	Type	Description
size	INT	The number of measurements in the profile.
constantValue	FLOAT	The fill value, default is 0.

Return values
Name	Type	Description
profile	OBJECT Profile	The new profile.

Sample

local profile = Profile.create(size, constantValue)

createFromPoints()

Short description

Creates a new profile from a vector of points. Coordinate system handling: For 2D points the profile will have EXPLICIT_1D coordinates, where the x-coordinates will become the coordinates in the Profile and the y-coordinates will become the corresponding values. For 3D points the profile will have EXPLICIT_2D coordinates, where the x,y-coordinates will become the coordinates in the Profile and the z-coordinates will become the corresponding values.

Keywords

convert

Parameters
Name	Type	Description
points	CONST_OBJECT Point	The vector of points.

Return values
Name	Type	Description
profile	OBJECT Profile	The new profile.

Sample

local profile = Profile.createFromPoints(points)

createFromVector()

Short description

Creates a new profile from a vector of measurement values, coordinates and valid flags. Coordinate system handling: The coordinate vector is optional, if not supplied 1D implicit coordinates starting at 0 with delta 1 is created. If supplied it can be both a float vector or a vector of 2D Points. An explicit coordinate representation is then created. Valid flags handling: The valid flags vector is optional. If no vector is supplied the global flag to use the valid flags is turned off. If supplied it must have the same length as the measurement vector, with 0 meaning that the corresponding measurement is invalid and non-zero that it is valid.

Keywords

convert

See also

Profile.clone, Profile.toVector

Parameters
Name	Type	Description
values	FLOAT	The vector of measurement values.
coordinates	CONST_AUTO	Optional vector of world coordinates (float or 2D points).
flags	INT	Optional vector of valid flags of the same length as the measurement vector.

Return values
Name	Type	Description
profile	OBJECT Profile	The new profile.

Sample

local profile = Profile.createFromVector(values, coordinates, flags)

crop()

Short description

Creates a new profile by cropping a segment of another profile. Coordinate system handling: The coordinate representation of the output profile is modified: If an implicit coordinate representation is used, the start coordinate is adjusted. If an explicit representation is used, the coordinate vector is cropped accordingly. Valid flags handling: The valid flags vector is cropped also if it exists.

Keywords

range, sub profile, region

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	Input profile
startIndex	INT	The start index, zero-based indexing.
stopIndex	INT	The end index, zero-based indexing.

Return values
Name	Type	Description
croppedProfile	OBJECT Profile	The new cropped profile. Returns nil if any index is out-of-range or if stop index is smaller than start index.

Sample

local croppedProfile = Profile.crop(profile, startIndex, stopIndex)

difference()

Short description

Calculates the absolute or squared difference between two profiles, sample-wise. The two profiles must have the same number of samples. Coordinate system handling: The coordinate representation of the first input profile is copied to the output profile. Valid flags handling: Both input profiles must have a valid measurement to produce a valid output for an index.

Keywords

ssd, sad

Parameters
Name	Type	Description
profile1	CONST_OBJECT Profile	The first source profile.
profile2	CONST_OBJECT Profile	The second source profile.
mode	ENUM DifferenceMode	Absolute or squared difference (ABS or SQUARE).

Return values
Name	Type	Description
result	OBJECT Profile	The difference profile.

Sample

local result = Profile.difference(profile1, profile2, mode)

differenceInplace()

Short description

In-place version of the Profile.difference function that modifies the input profile. See base function for full documentation.

Keywords

ssd, sad

Parameters
Name	Type	Description
profile1	OBJECT Profile	The first source profile. This profile is overwritten with the result of the difference.
profile2	CONST_OBJECT Profile	The second source profile.
mode	ENUM DifferenceMode	Absolute or squared difference (ABS or SQUARE).

Return values
Name	Type	Description
result	OBJECT Profile	Reference to the result profile.

Sample

local result = Profile.differenceInplace(profile1, profile2, mode)

divide()

Short description

Divides the first profile with the second, sample-wise. The two profiles must have the same number of samples. If division-by-zero occurs, the corresponding output is set to zero. Coordinate system handling: The coordinate representation of the first input profile is copied to the output profile. Valid flags handling: The valid flags of the output are enabled if any of the inputs have their flags enabled. Both input profiles must have a valid measurement to produce a valid output for an index. If output valid flags are enabled, division-by-zero sets the corresponding valid flag to false.

See also

Profile.divideInplace

Parameters
Name	Type	Description
profile1	CONST_OBJECT Profile	The first source profile.
profile2	CONST_OBJECT Profile	The second source profile.

Return values
Name	Type	Description
result	OBJECT Profile	The resulting profile.

Sample

local result = Profile.divide(profile1, profile2)

divideInplace()

Short description

In-place version of the Profile.divide function that modifies the input profile. See base function for full documentation.

See also

Profile.divide

Parameters
Name	Type	Description
profile1	OBJECT Profile	The first source profile. This profile is overwritten with the result of the division.
profile2	CONST_OBJECT Profile	The second source profile.

Return values
Name	Type	Description
result	OBJECT Profile	Reference to the result profile.

Sample

local result = Profile.divideInplace(profile1, profile2)

fillInvalidValues()

Short description

Fills in invalid values in a profile using neighboring valid values. A number of different ways interpolation methods are available: LINEAR: Fills invalid values using linear interpolation. Maximum length of invalid value region can be specified with fillParam. N invalid in a row is filled if N is smaller or equal to fillParam. All invalid are filled if fillParam is unspecified. NEIGHBOR_MIN: Fills invalid values with the min value of the two neighboring valid values. NEIGHBOR_MAX: Fills invalid values with the max value of the two neighboring valid values. NEIGHBOR_MEAN: Fills invalid values with the mean value of the two neighboring valid values. Valid flags handling: If no maximum length of invalid regions is specified all invalid values are filled and UseValidFlag is set to false.

Keywords

interpolation, missing data

See also

Profile.fillInvalidValuesWithReference

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The source profile.
fillMethod	ENUM FillInvalidMethod	Method to use when filling invalid values.
maxGap	INT	Maximum gap of invalid samples to fill. Default: infinite.

Return values
Name	Type	Description
result	OBJECT Profile	The filled profile.

Sample

local result = Profile.fillInvalidValues(profile, fillMethod, maxGap)

fillInvalidValuesWithReference()

Short description

Fills invalid values with corresponding values in a reference profile. Valid flags handling: All samples in the reference profile is assumed to be valid. Thus, a invalid sample in the input profile is always replaced with corresponding value in the reference profile. UseValidFlag is set to false in result profile.

Keywords

interpolation, missing data

See also

Profile.fillInvalidValues

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The source profile.
referenceProfile	CONST_OBJECT Profile	The reference profile of equal length as the source profile.

Return values
Name	Type	Description
result	OBJECT Profile	The filled profile.

Sample

local result = Profile.fillInvalidValuesWithReference(profile, referenceProfile)

findEqual()

Short description

Finds elements in a profile equal to a given value, within a give tolerance. Valid flags handling: Only the valid measurements are considered in the calculation.

Keywords

value, search

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The source profile.
value	FLOAT	Value to find.
epsilon	FLOAT	Tolerance interval. Default: eps of float32

Return values
Name	Type	Description
indices	INT	Indices of found elements.

Sample

local indices = Profile.findEqual(profile, value, epsilon)

findLocalExtrema()

Short description

Finds local extreme points (minima or maxima) of a Profile. A point is a local maximum if it is larger than all points within a neighborhood of the specified size. An optional contrast threshold level can be defined that sets a required value difference between the local maximum and the values on each side of the maximum, within the neighborhood. For locally maximal plateaus, where several measurements in the profile have the exact same value, only the leftmost value is reported. An optional absolute threshold can be specified, if so, point values must exceed the absolute threshold to be reported. Local minima are detected in a similar way. If contrastDifferenceMode ONE is selected (default), there must be at least one valid value on each side that is further from the extremal point than contrastThreshold. If contrastDifferenceMode ALL is selected, there must be at least one valid value on each side, and all valid values must be further from the extremal point than contrastThreshold. For non-closed profiles, the entire neighborhood must fit within the profile. E.g., if neighborhoodSize = 5, no extreme points will be detected at the first and last 2 measurements. Closed profiles are handled by wrap-around of the neighborhood. Coordinate system handling: The coordinate representation is not considered in this operation, the indices of the extremal points are returned. Valid flags handling: A maxima or minima can never be reported at positions with invalid data, but invalid data can be contained in the local neighborhood around a reported extreme point. When determining if a point is an extreme point, invalid data points within the local neighborhood are ignored.

Keywords

extreme, local maximum, local minimum, valley, peak

See also

Profile.findKnees

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The source profile.
extremaType	ENUM ExtremaType	Which type of extrema to look for. MIN or MAX.
neighborhoodSize	INT	The neighborhood size, expressed as number of samples. Must be odd and >= 3. Default is 3.
contrastThreshold	FLOAT	Required height of the peak/valley (value difference between the extreme point and surrounding points). Set to zero to disable (default).
contrastDifferenceMode	ENUM ContrastDifferenceMode	Determines how the difference between the extreme point and the surrounding points is calculated. Default is ONE, there must be at least one valid value on each side that is further from the extremal point than contrastThreshold.
absoluteThreshold	FLOAT	Absolute threshold, extremal points must be beyond this value to be included in the output. By default, this threshold is not used.

Return values
Name	Type	Description
extremaPositions	INT	Positions of the detected min or max points expressed as sample indices (zero-based). Nil if invalid parameters are provided.

Sample

local extremaPositions = Profile.findLocalExtrema(profile, extremaType, neighborhoodSize, contrastThreshold, contrastDifferenceMode, absoluteThreshold)

findRangeEdges()

Short description

Finds points in a range data profile that are likely to correspond to edges of physical objects. Although this function can be run on profiles from any source, it is developed with range data from laser devices in mind. The algorithm looks for points where the profile has a sharp knee near a discontinuity or fast transition between a low and a high level. A differenceStep parameter determines the width over which the value transition is measured, i.e., Step 1: [1 0 -1], Step 2: [1 0 0 0 -1], and so on. This parameter should be tuned such that the filter spans the entire low-high transition. Coordinate system handling: The coordinate representation is not considered in this operation. Valid flags handling: If side = HIGH, this function reports edge points at transitions between valid and invalid measurements. This is because the low side of a physical 3D edge often contains invalid measurements due to shadowing of the laser line. For edges detected at such transitions between valid and invalid measurements, the minStrength parameter is ignored. If side = LOW, edges are only reported where the non-zero filter coefficients hit valid measurements.

Keywords

corner, discontinuity, step

See also

Profile.findSlopes, Profile.findKnees

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The source profile.
differenceStep	INT	The central difference step.
polarity	ENUM SlopePolarity	Slope polarity. POSITIVE (rising slope) or NEGATIVE (falling slope).
minStrength	FLOAT	Threshold on the magnitude central difference filter response. Only slopes with a strength larger than this threshold are reported.
side	ENUM EdgeSide	Side of the range edge (HIGH or LOW side).

Return values
Name	Type	Description
subsampleIndex	FLOAT	Index with subsample (float) precision of the found edge points. Nil if invalid parameters are provided.

Sample

local subsampleIdx = Profile.findRangeEdges(profile, differenceStep, polarity, minStrength, side)

fourierTransform()

Short description

Calculates the Fourier transform of a profile. A sampled Fourier transform is returned distributed over one profile with magnitude values and one profile with phase values. The coordinates of the output profiles are adjusted to fit the input profile coordinates. E.g. if the input coordinates are in seconds, the output profile coordinates are in Hertz. If the input coordinates are in meters, the output coordinates are in cycles per meter and so on. The input profile coordinates must be of type implicit 1D (see Profile.setImplicitCoordinates). Missing values are not supported. The input profile can be zero-padded to a given length to increase the apparent frequency resolution of the output. If the transformLength parameter is smaller than the length of the input profile, the full input profile is used and no padding occurs. Set the smoothWindow flag true to apply a smooth window function to the profile prior to transformation. Using a smooth window makes the side lobes decay faster but also makes the main lobe wider and lower, i.e. low amplitude components become easier to detect but frequencies close to each other may merge into the same peak in the amplitude spectrum. Only the positive-frequency half spectrum is returned as the input is a real signal. The output frequency range is from zero to half the sampling frequency 0.5 * 1/T, where T is the sample distance of the input profile (for even size input profiles). N/2 + 1 output samples are created, where N is the number of input samples. If the first sample of the input profile is not at coordinate zero, the output phase is adjusted to match the translation of the input. Magnitude values are normalized to match the DC-level and half the amplitude of pure sinusoidal inputs, i.e. the transform of the profile a + b*sin(2*pi*f*t) will have a magnitude profile with value a at zero and value b/2 at f. Valid flags handling: Only profiles with disabled validity flags are allowed. Raw DFT mode: By setting the rawDFT flag true, most checks of the input and all scaling of the output are removed and a DFT is performed directly on all the values in the input profile. The transformLength parameter is ignored and no smoothed window is used. Coordinates and validity flags are ignored and the output coordinate system is not related to frequencies. The result is returned in Cartesian form, the first profile with the real part and the second profile contains the imaginary part. The full spectrum is returned, the first sample is the DC-component.

Keywords

dft, frequency, spectrum, fft

See also

Profile.inverseFourierTransform

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The source profile.
smoothWindow	BOOL	If set, a smooth window function (Hann window) is applied to the profile prior to transformation. Default is false, i.e. a box window is used. Ignored in raw mode.
transformLength	INT	The target transform length, if the input profile is shorter it is zero padded. Ignored in raw mode.
rawDFT	BOOL	Set to true to use raw DFT mode, default is false.

Return values
Name	Type	Description
magnitude	OBJECT Profile	The magnitude profile. The real part in raw mode.
phase	OBJECT Profile	The phase profile. The imaginary part in raw mode.

Sample

local magnitude, phase = Profile.fourierTransform(profile, smoothWindow, transformLength, rawDFT)

fourierTransformInverse()

Short description

Calculates the inverse Fourier transform. This function is the inverse of fourierTransform(), taking one magnitude profile and one phase profile and calculating the corresponding profile. The input profiles should have the first frequency sample at 0 and the last frequency sample at half the time domain sampling frequency, as created by fourierTransform(). The output is always calculated starting at zero offset and will have 2*(N-1) samples, where N is the number of samples in the input. The output coordinate system matches the input coordinate system, e.g. if the input coordinates are in hertz, the output coordinates are in seconds. If the coordinate systems specified in the magnitude profile and phase profile differ, the magnitude coordinate system is used. Note that this means that the returned profile will always have an even number of samples even if the originally transformed profile had an odd number of samples. Further, this function always recreates the part of the signal starting at time/position zero, which may not be where the original profile was sampled. Valid flags handling: Only profiles with disabled validity flags are allowed. Raw DFT mode: By setting the rawDFT flag true, most checks of the input and all scaling of the output are removed and an IDFT is performed directly on all the values in the input profile. In raw mode, input is expected to be in Cartesian form (first profile is the real part, second profile is the imaginary part) and the full spectrum is expected, starting with the DC component at the first sample. Coordinates and validity flags are ignored and the output coordinate system is not related to the input. The result is returned in Cartesian form, the first profile with the real part and the second profile contains the imaginary part.

Keywords

frequency, idft, spectrum, ifft

See also

Profile.fourierTransform

Parameters
Name	Type	Description
magnitude	CONST_OBJECT Profile	The input magnitude profile. The real part in raw mode.
phase	CONST_OBJECT Profile	The input phase profile. The imaginary part in raw mode.
rawDFT	BOOL	Set to true to use raw DFT mode, default is false.

Return values
Name	Type	Description
profile	OBJECT Profile	The resulting profile. The real part of the result in raw mode.
imaginaryPart	OBJECT Profile	Only used in raw mode, the imaginary part of the result.

Sample

local profile, imaginaryPart = Profile.fourierTransformInverse(magnitude, phase, rawDFT)

gauss()

Short description

Smooths a profile using a Gauss filter kernel. Coordinate system handling: The coordinate representation is not considered in this operation. The filter operation wraps around if the isClosed-flag is on. Valid flags handling: Only the valid measurements are considered in the calculation. By default, all invalid measurements will be marked as invalid also in the output. If the fill flag is set to true, invalid measurements will be filled with filtered neighbor values where possible.

Keywords

filter, low pass, lp, smooth

See also

Profile.median, Profile.blur

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	Input profile.
kernelSize	INT	Size of the kernel, must be positive, odd and smaller than the profile length.
fillInvalid	BOOL	Optional flag to also fill in invalid values while filtering. Default is false.

Return values
Name	Type	Description
smoothProfile	OBJECT Profile	Output profile, smoothed by the Gauss filter.

Sample

local smoothProfile = Profile.gauss(profile, kernelSize)

gaussDerivative()

Short description

Differentiates a profile using a Gaussian derivative filter kernel. The filter is normalized such that the overall magnitude of the output is independent of the filter size. Coordinate system handling: The coordinate representation is not considered in this operation. The filter operation wraps around if the isClosed-flag is on. Valid flags handling: Invalid flags are not allowed in this operation.

Keywords

first, slope

See also

Profile.centralDifference

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	Input profile.
kernelSizeSamples	INT	Size of the kernel, must be positive and odd.
order	ENUM DifferentiationOrder	FIRST gives first order derivative and SECOND gives second order derivative.

Return values
Name	Type	Description
derivativeProfile	OBJECT Profile	Output profile, differentiated by the Gaussian derivative filter.

Sample

local derivativeProfile = Profile.gaussDerivative(profile, kernelSizeSamples, order)

getArea()

Short description

Returns estimate of the signed area of the measurements in the profile. In addition, the number of valid measurements is also returned. The function is vectorized so that it is possible to operate on a vector of profiles. Signed area: Negative values contribute with negative area. Coordinate system handling: The coordinate representation is not considered in this operation. Valid flags handling: Only the valid measurements are considered in the calculation.

Keywords

riemann, integral

See also

Profile.getSum

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The source profile or vector of profiles.

Return values
Name	Type	Description
area	FLOAT	The estimated area.
validCount	INT	The number of valid measurements per profile.

Sample

local area, validCount = Profile.getArea(profile)

getClosed()

Short description

Returns if the closed flag is enabled. If the flag is enabled, the profile is considered closed, meaning that the first measurement follows after the last. This affects the border handling of some operations such as filtering algorithms.

Keywords

circular, infinite, periodic

See also

Profile.setClosed

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The profile object.

Return values
Name	Type	Description
isClosed	BOOL	Indicating if the profile is closed.

Sample

local isClosed = Profile.getClosed(profile)

getCoordinate()

Short description

Returns the coordinates of the given index or vector of indexes.

Keywords

location, position, spatial

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The profile object.
index	INT	The index or vector of indexes. Zero-based indexing.

Return values
Name	Type	Description
coordinate	AUTO	The world coordinate(s), a (vector of) floating point number(s) for 1D coordinates and a (vector of) 2D point(s) for 2D coordinates. Returns nil if any index is out-of-range.

Sample

local coordinate = Profile.getCoordinate(profile, index)

getCoordinateType()

Short description

Return the used coordinate representation type. Possible coordinate types: IMPLICIT_1D, EXPLICIT_1D, IMPLICIT_2D, EXPLICIT_2D.

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The profile object.

Return values
Name	Type	Description
coordinateType	ENUM CoordinateType	The coordinate type.

Sample

coordinateType = Profile.getCoordinateType(profile)

getDistance()

Short description

Returns the Euclidian distances between two specified profile elements. Two distances are returned, one along the coordinate axis and one between the two points represented by the (coordinate, value) pairs. For example, if the coordinates represent 2D points, the distances are calculated as follows respectively: coordinage distance: sqrt(dX^2 + dY^2) total distance: sqrt(dX^2 + dY^2 + dValue^2)

Keywords

euclidian

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The profile object.
index1	INT	Index of sample 1 or vector with indices.
index2	INT	Index of sample 2 or vector with indices..

Return values
Name	Type	Description
coordDist	FLOAT	Distance in the coordinate dimensions (Euclidean distance).
totalDist	FLOAT	Distance in the value + coordinate dimensions (Euclidean distance).

Sample

local coordDist, totalDist = Profile.getDistance(profile, index1, index2)

getHistogram()

Short description

Returns the histogram of the values in a profile or a set of profiles. The bin centers are returned as the coordinates in the result profile. Values outside the bins (minValue,maxValue) are discarded. Valid flags handling: Only the valid measurements are considered in the calculation.

Keywords

distribution, statistics

Parameters
Name	Type	Description
profiles	CONST_OBJECT Profile	The source profiles.
binCount	INT	The number of bins to be used in the histogram. If no value is specified the default number of bins (32) is used.
minValue	FLOAT	The minimum value of the histogram. If no value is specified an automatic value based on the minimum value of all profiles will be used.
maxValue	FLOAT	The maximum value of the histogram. If no value is specified an automatic value based on the maximum value of all profiles will be used.

Return values
Name	Type	Description
histogram	OBJECT Profile	Histogram, represented as a profile. The profile coordinates is the center of each histogram bin.

Sample

local histogram = Profile.getHistogram(profiles, binCount, minValue, maxValue)

getIntersectionAngle()

Short description

Measures angle between two lines fitted around a given position in the input profile. One line is fitted to samples to the left of the given position and the other to the right using a robust RANSAC least squares fitting. The measured angle is between 0 and 2*PI, and is measured above the profile. Thus, a valley ( \/ ) gives an angle smaller than PI and a peak ( /\ ) an angle larger than PI (if \/ = a then /\ = 2*PI - a). Coordinate system handling: The coordinate are considered in the line fitting operation. The coordinate system of the profile must be 1D. Valid flags handling: Only valid values from the input profiles are used.

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The source profile.
position	INT	Position to estimate lines around expressed as a sample index.
regionSize	INT	Size of region(s), expressed in samples, to the left and right of the given position to use for line fitting. With a scalar input the left and right regions are of equal size. If vector the first value is the size of the left region and the second the size of the right region.
skipSize	INT	Skip samples before the region start to produce a gap to the given position for the line fitting. With a vector input, a different number of samples can be skipped to the left and right respectively.
iterations	INT	Number of iterations in the RANSAC loop in the line fitting. Default value is 200. Can be reduced if there are few or no outliers.

Return values
Name	Type	Description
angleRad	FLOAT	Intersection angle, in radians.
intersectionPoint	OBJECT Point	Intersection point of the lines, expressed as a 2D Point using (coordinate, value) as components.
leftLine	OBJECT Profile.Curve	Left line.
rightLine	OBJECT Profile.Curve	Right line.

Sample

local angleRad, intersectionPoint, leftLine, rightLine = Profile.getIntersectionAngle(profile, position, regionSize, skipSize, iterations)

getMax()

Short description

Returns the maximum value of a profile. In addition, the (first) index and the number of valid measurements are also returned. The function is vectorized so that it is possible to operate on a vector of profiles. For empty profiles or profiles without valid data, zero is returned for both maxValue and validCount. Start and stop indices (inclusive) can be used to calculate the maximum on a part of the profile(s). Coordinate system handling: The coordinate representation is not considered in this operation. Valid flags handling: Only the valid measurements are considered in the calculation.

Keywords

maximum

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The source profile or vector of profiles.
startIndex	INT	Start index of search range.
stopIndex	INT	Stop index of search range.

Return values
Name	Type	Description
maxValue	FLOAT	The maximum value for each input profile.
index	INT	The (first) index at which the maximum value is located. Vector output if a vector of profiles is given as input.
validCount	INT	The number of valid measurements per input profile.

Sample

local maxValue, index, validCount = Profile.getMax(profile)

getMean()

Short description

Returns the mean value of a profile. In addition, the number of valid measurements is also returned. The function is vectorized so that it is possible to operate on a vector of profiles. For empty profiles or profiles without valid data, zero is returned for both meanValue and validCount. Start and stop indices (inclusive) can be used to calculate the mean on a part of the profile(s). Coordinate system handling: The coordinate representation is not considered in this operation. Valid flags handling: Only the valid measurements are considered in the calculation.

Keywords

statistics, average

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The source profile or vector of profiles.
startIndex	INT	Start index of search range.
stopIndex	INT	Stop index of search range.

Return values
Name	Type	Description
meanValue	FLOAT	The mean value, one value for each profile.
validCount	INT	The number of valid elements per profile.

Sample

local meanValue, validCount = Profile.getMean(profile)

getMedian()

Short description

Returns the median value of a profile. In addition, the number of valid measurements is also returned. The function is vectorized so that it is possible to operate on a vector of profiles. For empty profiles or profiles without valid data, zero is returned for both medianValue and validCount. Start and stop indices (inclusive) can be used to calculate the median on a part of the profile(s). Coordinate system handling: The coordinate representation is not considered in this operation. Valid flags handling: Only the valid measurements are considered in the calculation.

Keywords

statistics, percentile

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The source profile or vector of profiles.
startIndex	INT	Start index of search range.
stopIndex	INT	Stop index of search range.

Return values
Name	Type	Description
medianValue	FLOAT	The median value, one value for each profile.
validCount	INT	The number of valid measurements per profile.

Sample

local medianValue, validCount = Profile.getMedian(profile)

getMin()

Short description

Returns the minimum value of a profile. In addition, the (first) index and the number of valid measurements are also returned. The function is vectorized so that it is possible to operate on a vector of profiles. For empty profiles or profiles without valid data, zero is returned for both minValue and validCount. Start and stop indices (inclusive) can be used to calculate the minimum on a part of the profile(s). Coordinate system handling: The coordinate representation is not considered in this operation. Valid flags handling: Only the valid measurements are considered in the calculation.

Keywords

minimum

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The source profile or vector of profiles.
startIndex	INT	Start index of search range.
stopIndex	INT	Stop index of search range.

Return values
Name	Type	Description
minValue	FLOAT	The minimum value for each input profile.
index	INT	The (first) index at which the minimum value is located. Vector output if a vector of profiles is given as input.
validCount	INT	The number of valid measurements per input profile.

Sample

local minValue, index, validCount = Profile.getMin(profile)

getSize()

Short description

Returns the number of measurements in the profile.

Keywords

width, length

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The profile object.

Return values
Name	Type	Description
size	INT	The number of measurements in the profile.

Sample

local size = Profile.getSize(profile)

getStandardDeviation()

Short description

Returns both the mean and standard deviation of the measurements in a profile. In addition, the number of valid measurements is also returned. The function is vectorized so that it is possible to operate on a vector of profiles. For empty profiles or profiles without valid data, zero is returned for meanValue, stdDev and validCount. Start and stop indices (inclusive) can be used to calculate the standard deviation on a part of the profile(s). Coordinate system handling: The coordinate representation is not considered in this operation. Valid flags handling: Only the valid measurements are considered in the calculation.

Keywords

statistics, variance

Parameters
Name	Type	Description
profiles	CONST_OBJECT Profile	The source profile or vector of profiles.
startIndex	INT	Start index of search range.
stopIndex	INT	Stop index of search range.

Return values
Name	Type	Description
meanValue	FLOAT	The mean value for each profile.
stdDev	FLOAT	The standard deviation (maximum likelihood estimate), for each profile.
validCount	INT	The number of valid measurements per profile.

Sample

local meanValue, stdDev, validCount = Profile.getStandardDeviation(profile)

getSum()

Short description

Returns the sum of the measurement of a profile. In addition, the number of valid measurements is also returned. The function is vectorized so that it is possible to operate on a vector of profiles. Zero is returned for profiles without valid data. Start and stop indices (inclusive) can be used to calculate the sum on a part of the profile(s). Valid flags handling: Only the valid measurements are considered in the calculation.

Keywords

integral, statistics, summation, total

See also

Profile.getArea

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The source profile or vector of profiles.
startIndex	INT	Start index of search range.
stopIndex	INT	Stop index of search range.

Return values
Name	Type	Description
sum	FLOAT	The sum, one sum for each profile.
validCount	INT	The number of valid measurements per profile.

Sample

local sumValue, validCount = Profile.getSum(profile)

getValidCount()

Short description

Get the number of valid elements in a profile or set of profiles, one count for each profile is returned. If valid flags are not used validCount = profile.Size().

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The profile or profiles.

Return values
Name	Type	Description
validCount	INT	Number of valid elements.

Sample

 local validCount = Profile.getValidCount(profile)

getValidFlag()

Short description

Returns the valid flag of the measurements at the given index or vector of indexes.

Keywords

missing data

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The profile object.
index	INT	The index or vector of indexes. Zero-based indexing.

Return values
Name	Type	Description
flag	INT	The valid flag. 0 means invalid data and non-zero valid data. Returns nil if any index is out-of-range.

Sample

local flag = Profile.getValidFlag(profile, index)

getValidFlagsEnabled()

Short description

Checks if global usage of valid flags is enabled. 'False' means that all measurement values are treated as valid regardless of the valid flags vector. 'True' means that the valid flag is regarded for each measurement.

Keywords

missing data

See also

Profile.setValidFlagsEnabled

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The profile object.

Return values
Name	Type	Description
validFlagsEnabled	BOOL	Indicating if the valid flags are enabled.

Sample

local validFlagsEnabled = Profile.getValidFlagsEnabled(profile)

getValue()

Short description

Returns the measurement values of a profile at the provided index or indexes.

Keywords

sample, element

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The profile object.
index	INT	The index or vector if indexes to get. Zero-based indexing.

Return values
Name	Type	Description
value	FLOAT	The value(s). Returns nil if any index is out-of-range.

Sample

local value = Profile.getValue(profile, index)

interpolateCoordinate()

Short description

Returns coordinate(s) which are linearly interpolated between the two closest indexes in the profile. Coordinate system handling: The function returns 2D Points for profiles with 2D coordinates and floats for profiles with 1D coordinates. Valid flags handling: Valid flags are not considered in this function.

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The profile.
indexFloat	FLOAT	Index or indexes in floating point precision. Zero-based indexing.

Return values
Name	Type	Description
coordinate	AUTO	The world coordinate(s) as a single value/point or as a vector of values/points. Returns nil if any index is out-of-range.

Sample

local coordinate = Profile.interpolateCoordinate(profile, indexFloat)

load()

Short description

Imports a profile from the specified file path. The format is defined by the file extension: .csv: Comma-separated value file .json: JSON (native AppSpace format) .msgpack: MessagePack (native AppSpace format) The csv-file should have numbers written as text, separated by at least one character that is not normally used in numbers (e.g. tab, semicolon, colon, etc.). Only decimal points are accepted, commas are interpreted as delimiters between entries. Values like -1.555e-3 are accepted. Regular spaces are ignored. The first row is taken as values for the profile. If the second row is equal in length, those numbers are interpreted as validity flags (zero means invalid, nonzero means valid). If the third row is equal in length, those numbers are interpreted as coordinates for the samples. Coordinates should be monotonically increasing. Coordinate system handling: If no coordinate row of correct length is present, the coordinate representation will be implicit 1D, starting at 0 with a delta value of 1. If the coordinate row is valid, coordinates will be as given in the third row and of type explicit 1D. Valid flags handling: If no validity row of correct length is present, all measurements are considered as valid. No valid flags vector is created. If the validity mask row is present, the validity flags are set as given in the second row.

Keywords

import, csv

See also

Profile.gauss, Profile.blur

Parameters
Name	Type	Description
filepath	STRING	The path and name of the file to load the profile from.

Return values
Name	Type	Description
profile	OBJECT Profile	The new profile or nil on failure.

Sample

local profile = Profile.load("private/profile.csv")

median()

Short description

Smooths a profile using a median filter. Coordinate system handling: The coordinate representation is not considered in this operation. The filter operation wraps around if the isClosed-flag is on. Valid flags handling: Only the valid measurements are considered in the calculation. There is an option to fill in invalid values in the filter operation.

Keywords

filter, smooth

See also

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	Input profile.
kernelSize	INT	Size of the kernel, must be positive, odd and smaller than the profile length.
fillInvalid	BOOL	Optional flag to also fill in invalid values while filtering. Default is false.

Return values
Name	Type	Description
smoothProfile	OBJECT Profile	Output profile, filtered by the median filter.

Sample

local smoothProfile = Profile.median(profile, kernelSize)

mirror()

Short description

Mirrors the values and valid flags in the profile, so that the first sample is placed last and last sample placed first in the output profile. Note that the coordinates are not mirrored.

Keywords

flip

See also

Profile.mirrorInplace

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The source profile.

Return values
Name	Type	Description
result	OBJECT Profile	Mirrored profile.

Sample

local result = Profile.mirror(profile)

mirrorInplace()

Short description

In-place version of mirror that modifies the input profile. See base function for full documentation.

Keywords

flip

See also

Profile.mirror

Parameters
Name	Type	Description
profile	OBJECT Profile	The source profile and result profile.

Return values
Name	Type	Description
result	OBJECT Profile	Reference to the mirrored profile.

Sample

local result = Profile.mirrorInplace(profile)

multiply()

Short description

Multiplies two profiles sample-wise. The two profiles must have the same number of measurements. Coordinate system handling: The coordinate representation of the first input profile is copied to the output profile. Valid flags handling: Both input profiles must have a valid measurement to produce a valid output for an index.

Keywords

times

Parameters
Name	Type	Description
profile1	CONST_OBJECT Profile	The first source profile.
profile2	CONST_OBJECT Profile	The second source profile.

Return values
Name	Type	Description
result	OBJECT Profile	The product profile.

Sample

local result = Profile.multiply(profile1, profile2)

multiplyAddConstant()

Short description

Multiplies one profile with alpha, thereafter the constant beta is added. If the multiplication underflows/overflows, the result is underflow/overflow, regardless of the addition. Coordinate system handling: The coordinate representation of the input profile is copied to the output profile. Valid flags handling: The valid flags representation of the input profile is copied to the output profile.

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The source profile.
alpha	FLOAT	The constant to multiply with.
beta	FLOAT	The constant to add.

Return values
Name	Type	Description
result	OBJECT Profile	The resulting profile.

Sample

local result = Profile.multiplyAddConstant(profile, alpha, beta)

multiplyAddConstantInplace()

Short description

In-place version of the Profile.multiplyAddConstant function that modifies the input profile. See base function for full documentation.

Parameters
Name	Type	Description
profile1	OBJECT Profile	The first source profile. This profile is overwritten with the result of the multiplication and sum.
alpha	FLOAT	The constant to multiply with.
beta	FLOAT	The constant to add.

Return values
Name	Type	Description
result	OBJECT Profile	Reference to the result profile.

Sample

local result = Profile.multiplyAddConstantInplace(profile1, alpha, beta)

multiplyConstant()

Short description

Multiplies a profile with a constant. Coordinate system handling: The coordinate representation of the input profile is copied to the output profile. Valid flags handling: The valid flags representation of the input profile is copied to the output profile.

Keywords

scale

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The source profile.
constant	FLOAT	The constant to multiply the samples with.

Return values
Name	Type	Description
result	OBJECT Profile	The multiplied profile.

Sample

local result = Profile.multiplyConstant(profile, constant)

multiplyConstantInplace()

Short description

In-place version of the Profile.multiplyConstant function that modifies the input profile. See base function for full documentation.

Keywords

scale

Parameters
Name	Type	Description
profile1	OBJECT Profile	The first source profile. This profile is overwritten with the result of the multiplication.
constant	FLOAT	The constant to multiply the samples with.

Return values
Name	Type	Description
result	OBJECT Profile	Reference to the result profile.

Sample

local result = Profile.multiplyConstantInplace(profile1, constant)

multiplyInplace()

Short description

In-place version of the Profile.multiply function that modifies the input profile. See base function for full documentation.

Keywords

times

Parameters
Name	Type	Description
profile1	OBJECT Profile	The first source profile. This profile is overwritten with the result of the multiplication.
profile2	CONST_OBJECT Profile	The second source profile.

Return values
Name	Type	Description
result	OBJECT Profile	Reference to the result profile.

Sample

local result = Profile.multiplyInplace(profile1, profile2)

pow()

Short description

Raises each measurement value to the power of an exponent. Coordinate system handling: The coordinate representation of the input profile is copied to the output profile. Valid flags handling: The valid flags representation of the input profile is copied to the output profile.

Keywords

exponential, square, squared, power

See also

Profile.powInplace

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The source profile.
exponent	FLOAT	The exponent.

Return values
Name	Type	Description
result	OBJECT Profile	The resulting profile.

Sample

local result = Profile.pow(profile, exponent)

powInplace()

Short description

In-place version of the Profile.pow function that modifies the input profile. See base function for full documentation.

Keywords

exponential, square, squared, power

See also

Profile.pow

Parameters
Name	Type	Description
profile	OBJECT Profile	The source profile. This profile is overwritten with the result of the pow.
exponent	FLOAT	The exponent.

Return values
Name	Type	Description
result	OBJECT Profile	Reference to the result profile.

Sample

local result = Profile.powInplace(profile, exponent)

removeValidFlagVector()

Short description

Remove the valid flag vector from the profile.

Parameters
Name	Type	Description
profile	OBJECT Profile	The profile object.

Sample

 Profile.removeValidFlagVector(profile)

resize()

Short description

Samples the profile using the given number of samples and outputs these as a new profile. Linear interpolation is used. Both input and output profiles must have at least two samples. The new samples are placed equidistantly. For explicit 2D coordinates, the distance along the coordinate polygon is used. All input samples must have unique positions. Explicit 1D coordinates in the input profile must be strictly monotonic. Coordinate system handling: Implicit 1D coordinates are used for the output when the input coordinates are 1D (implicit or explicit). For 2D coordinates, the output coordinate type is the same as the input coordinate type. The closedness of the profile is taken into account when placing the new samples in all cases except for explicit 1D coordinates, where the wrap-around point is undefined. Valid flags handling: Valid flags are respected. Any output sample where at least one of the input samples used for interpolation is invalid, is marked as invalid.

Keywords

decimate, equidistant, interpolate, scale, subsample, resample

See also

Profile.resizeScale

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The profile to resize.
newSize	INT	The desired size of the new profile in samples.

Return values
Name	Type	Description
newProfile	OBJECT Profile	The new profile, or nil on error.

Sample

local newProfile = Profile.resize(profile, newSize)

resizeScale()

Short description

Samples the profile using the given scale factor of samples in relation to the number of samples in the input profile. E.g. a factor 2 generates twice as many samples in the new profile. Linear interpolation is used. Both input and output profiles must have at least two samples. The new samples are placed equidistantly. For explicit 2D coordinates, the distance along the coordinate polygon is used. All input samples must have unique positions. Explicit 1D coordinates in the input profile must be strictly monotonic. Coordinate system handling: Implicit 1D coordinates are used for the output when the input coordinates are 1D (implicit or explicit). For 2D coordinates, the output coordinate type is the same as the input coordinate type. The closedness of the profile is taken into account when placing the new samples in all cases except for explicit 1D coordinates, where the wrap-around point is undefined. Valid flags handling: Valid flags are respected. Any output sample where at least one of the input samples used for interpolation is invalid, is marked as invalid.

Keywords

decimate, equidistant, interpolate, scale, subsample, resample

See also

Profile.resize

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The profile to resize.
factor	FLOAT	Resize factor, e.g, 0.5 or 2.0.

Return values
Name	Type	Description
newProfile	OBJECT Profile	The new profile, or nil on error.

Sample

local newProfile = Profile.resizeScale(profile, factor)

rotate()

Short description

Rotates a profile in the value-coordinate plane. Only 1D coordinates are supported. Result is always in EXPLICIT_1D coordinates.

Keywords

transform

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The source profile.
rotationRad	FLOAT	Rotation in radians. A positive rotation is in the counterclockwise direction.
coordinateOrigin	FLOAT	Optional origin of rotation in the coordinate dimension. Default: 0.0
valueOrigin	FLOAT	Optional origin of rotation in the value dimension. Default: 0.0

Return values
Name	Type	Description
result	OBJECT Profile	Rotated profile. EXPLICIT_1D coordinates.

Sample

local result = Profile.rotate(profile, rotationRad, coordinateOrigin, valueOrigin)

rotateInplace()

Short description

In-place version of rotate. Only 1D coordinates are supported. Result is always in EXPLICIT_1D coordinates.

Keywords

transform

Parameters
Name	Type	Description
profile	OBJECT Profile	The profile to rotate. This profile is overwritten with the result of the rotation.
rotationRad	FLOAT	Rotation in radians. A positive rotation is in the counter clockwise direction.
coordinateOrigin	FLOAT	Optional origin of rotation in the coordinate dimension. Default: 0.0
valueOrigin	FLOAT	Optional origin of rotation in the value dimension. Default: 0.0

Return values
Name	Type	Description
result	OBJECT Profile	Reference to the rotated profile. EXPLICIT_1D coordinates.

Sample

local result = Profile.rotateInplace(profile, rotationRad, coordinateOrigin, valueOrigin)

save()

Short description

Writes a profile to the specified file path. Overwrites the file if it already exists. The format is defined by the file extension: .csv: Comma-separated value file, using a semicolon as separator. .json: JSON (native AppSpace format) .msgpack: MessagePack (native AppSpace format) For the csv-file format the first line contains the profile values. If the validity flags are active, the second line contains the flags (0 means invalid, 1 means valid). If coordinates are explicit 1D, the third line contains the coordinate of each sample. Coordinate system handling: Only 1D coordinates are supported. Implicit coordinates are not written to the file. Explicit coordinates are written to the third line in the output file. Valid flags handling: If the validity flags are active, those are written to the second line in the output file.

Keywords

export, csv

See also

Profile.getValidFlagsEnabled

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The profile to store.
filepath	STRING	The path and name of the file to write the profile to.

Return values
Name	Type	Description
success	BOOL	True on success, false on write error, nil if the call was malformed.

Sample

local success = Profile.save(profile, "private/profile.csv")

setClosed()

Short description

Sets the closed flag. If the flag is enabled, the profile is considered closed, meaning that the first measurement follows after the last. This affects the border handling of some algorithms. This operation does not affect any values, coordinates of measurements or valid flags.

Keywords

circular, infinite, periodic

See also

Profile.getClosed

Parameters
Name	Type	Description
profile	OBJECT Profile	The profile object.
setClosed	BOOL	Marking the profile as closed (true) or as open (false).

Sample

Profile.setClosed(profile, true)

setCoordinate()

Short description

Sets the coordinates of the given index or indexes. The dimensionality of the new coordinates must match those of the profile, e.g. only 2D coordinates can be set in a profile already using 2D coordinates. If the coordinate representation of the profile is implicit, it is silently converted to an explicit representation before updating coordinates. Use setImplicitCoordinates to setup an implicit coordinate system.

Keywords

location, position, spatial

Parameters
Name	Type	Description
profile	OBJECT Profile	The profile object.
index	INT	The index or vector of indexes. Zero-based indexing. Out-of-range indexes are ignored.
coordinate	CONST_AUTO	The world coordinates, a (vector of) floating point number(s) for 1D coordinates and a (vector of) 2D point(s) for 2D coordinates. The vector must be of the same length as the index vector.

Sample

Profile.setCoordinate(profile, index, coordinate)

setImplicitCoordinates()

Short description

Sets the coordinates of the profile to implicit type (the coordinates of the first sample and a difference between samples). Provide two floating point numbers to set 1D coordinates, or two 2D points to set 2D coordinates. Use setCoordinate to set explicit coordinates of specific samples.

Keywords

location, position, spatial

Parameters
Name	Type	Description
profile	OBJECT Profile	The profile object.
start	CONST_AUTO	The coordinates of the first sample, a scalar value or 2D Point.
delta	CONST_AUTO	The difference in position of each two consecutive samples, a scalar value or 2D Point.

Sample

Profile.setImplicitCoordinates(profile, start, delta)

setValidFlag()

Short description

Set the valid flags of a profile at the given index or vector of indexes. Sets the flags in the input profile (in-place).

Keywords

missing data

Parameters
Name	Type	Description
profile	OBJECT Profile	The profile object.
index	INT	The index or vector of indexes. Zero-based indexing. Out-of-range indexes are ignored.
flag	INT	The valid flag to set to the indices. 0 means invalid and non-zero means valid.

Sample

Profile.setValidFlag(profile, index, flag)

setValidFlagRange()

Short description

Set a range of valid flags in the input profile (inplace). Sets all valid flags between startIndex and stopIndex to the specified flag. If stopIndex is omitted all flags from startIndex to the end of the profile is set.

Parameters
Name	Type	Description
profile	OBJECT Profile	The profile object.
flag	INT	The valid flag or vector of valid flags, to set to the indices. 0 means invalid and non-zero means valid.
startIndex	INT	Start index or vector of start indices. Zero-based indexing.
stopIndex	INT	Stop index or vector of stop indices. Zero-based indexing. Optional.

Return values
Name	Type	Description
result	OBJECT Profile	Reference to the result profile.

Sample

result = Profile.setValidFlagRange(profile, flag, startIndex, stopIndex)

setValidFlagsEnabled()

Short description

Enables or disables the individual valid flag of each measurement. 'False' means that all measurement values are treated as valid regardless of the valid flags set. 'True' means that the valid flag is regarded for each measurement. If the flags are enabled and the profile did not contain a valid flags vector, the vector is generated.

Keywords

missing data

See also

Parameters
Name	Type	Description
profile	OBJECT Profile	The profile object.
validFlagsEnabled	BOOL	Activating or deactivating the usage of the valid data flags vector.

Sample

Profile.setValidFlagsEnabled(profile, validFlagsEnabled)

setValue()

Short description

Set a measurement value in a profile at one or multiple given position(s). Out-of-range indexes are ignored.

Keywords

sample, element

Parameters
Name	Type	Description
profile	OBJECT Profile	The profile object.
index	INT	The index or indexes to set. Zero-based indexing.
value	FLOAT	The measurement value to set.

Sample

Profile.setValue(profile, index, value)

shrink()

Short description

Sets all values within a threshold of a given level to that level. For example, with the default level zero, all values within +/- a threshold are set to zero. In denoising context, this is known as a shrinkage operation or hard thresholding. Coordinate system handling: The coordinate representation is copied to the output profile. Valid flags handling: Valid flags are copied to the output.

Keywords

denoise, hard thresholding, soft thresholding, clamp

See also

Profile.clamp, Profile.binarize

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The input profile.
threshold	FLOAT	Values within this distance of level is set to level.
level	FLOAT	The level to shrink around, default is zero.

Return values
Name	Type	Description
newProfile	OBJECT Profile	The new profile, or nil on error.

Sample

local newProfile = Profile.shrink(profile, threshold, level)

shrinkInplace()

Short description

Inplace version of the shrink function that modifies the input profile. See the base function for full documentation.

Keywords

denoise, hard thresholding, soft thresholding, clamp

See also

Profile.clampInplace, Profile.binarize

Parameters
Name	Type	Description
profile	OBJECT Profile	The profile.
threshold	FLOAT	Values within this distance of level is set to level.
level	FLOAT	The level to shrink around, default is zero.

Sample

Profile.shrinkInplace(profile, threshold, level)

sort()

Short description

Sort a profile with respect to sample values or coordinates. The validity flags and explicit coordinates follow the samples while sorting. Implicit coordinates are unaffected by sorting. When sorting by coordinates, explicit 1D coordinates must be used. A stable sorting algorithm is used, such that samples with equal value do not change order internally. Invalid values are sorted as if marked as valid, but their invalidity flag is kept.

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The source profile.
ascending	BOOL	True if profile is to be sorted in ascending order. Optional, default is true.
key	ENUM SortKey	Indicates if samples are to be sorted by value or by coordinate. Optional, default is sorting by value.

Return values
Name	Type	Description
result	OBJECT Profile	Sorted profile.
index	INT	Vector of indices indicating the effect of the sorting operation. The first entry indicates what sample in the input that ended up first in the output. Indices are zero-based.

Sample

local result, index = Profile.sort(profile, ascending, key)

subtract()

Short description

Subtracts the second profile from the first, sample-wise. The two profiles must have the same number of samples. Coordinate system handling: The coordinate representation of the first input profile is copied to the output profile. Valid flags handling: Both input profiles must have a valid measurement to produce a valid output for an index.

Keywords

minus

Parameters
Name	Type	Description
profile1	CONST_OBJECT Profile	The first source profile.
profile2	CONST_OBJECT Profile	The second source profile.

Return values
Name	Type	Description
result	OBJECT Profile	The difference profile.

Sample

local result = Profile.subtract(profile1, profile2)

subtractInplace()

Short description

In-place version of the Profile.subtract function that modifies the input profile. See base function for full documentation.

Keywords

minus

Parameters
Name	Type	Description
profile1	OBJECT Profile	The first source profile. This profile is overwritten with the result of the difference.
profile2	CONST_OBJECT Profile	The second source profile.

Return values
Name	Type	Description
result	OBJECT Profile	Reference to the result profile.

Sample

local result = Profile.subtractInplace(profile1, profile2)

threshold()

Short description

Return the indices of all valid profile values between the upper and lower threshold. Any threshold can be left out, in which case it has no influence on the selection. Coordinate system handling: The positions of the samples do not influence the function. Missing data handling: Only valid samples are included in the output.

Keywords

region, segmentation

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	Input profile.
lowerThreshold	FLOAT	Lower threshold. Optional, default is no lower threshold (no lower limit on sample value).
upperThreshold	FLOAT	Upper threshold. Optional, default is no upper threshold (no upper limit on sample value).

Return values
Name	Type	Description
indices	INT	Zero-based indices to all valid samples between the upper and lower threshold.

Sample

local indices = Profile.threshold(profile, lowerThreshold, upperThreshold)

toImage()

Short description

Convert a vector of profiles to an image, stacked vertically. The coordinates in the profiles are not used. Valid flags handling: If any of the input profiles has valid flags enabled, the resulting image will have missing data enabled. In that case, any pixel corresponding to an invalid sample in the profile will be stored as missing data in the image.

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The source profile or vector of profiles.
type	ENUM ImageType	The pixel type of the resulting image.
pixelSizeZ	FLOAT	The pixel size in the z-dimension in world coordinates, e.g., the number of millimeters each pixel value integer increment corresponds to. (Default value: 1.0). By selecting 0.0 the scale will be automatically selected.
minZ	FLOAT	The smallest value that is represented in the output image. (Default value: 0.0).

Return values
Name	Type	Description
result	OBJECT Image	Resulting image.

Sample

local result = Profile.toImage(profile, type, pixelSizeZ, minZ)

toString()

Short description

Gets a user-friendly string description of the profile.

Keywords

description, help, print

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The profile object.

Return values
Name	Type	Description
str	STRING	User-friendly description of the profile.

Sample

local str = Profile.toString(profile)

toVector()

Short description

Returns the measurement values, coordinates and valid flags of a profile as vectors. Coordinate system handling: A coordinate vector of the same length as the measurement vector is returned. If the coordinate representation is of implicit type, the vector is calculated. Valid flags handling: If the valid flags are disabled, no flags are returned.

Keywords

convert

See also

Profile.createFromVector

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The profile.

Return values
Name	Type	Description
values	FLOAT	The vector of measurement values, or nil if the profile is not valid.
coordinates	CONST_AUTO	Vector of world coordinates (floats or 2D points), nor nil if the profile is not valid.
flags	INT	Vector of valid data flags, or nil if the flags are not enabled.

Sample

local values, coordinates, flags = Profile.toVector(profile)

translate()

Short description

Translates a profile in the coordinate dimension and/or in the value dimension. Only 1D coordinates are supported.

Keywords

move, shift, transform

Parameters
Name	Type	Description
profile	CONST_OBJECT Profile	The source profile.
coordinateTranslation	FLOAT	Translation of coordinates.
valueTranslation	FLOAT	Translation of values.

Return values
Name	Type	Description
result	OBJECT Profile	Translated profile.

Sample

local result = Profile.translate(profile, coordinateTranslation, valueTranslation)

translateInplace()

Short description

In-place version of translate, see base function for full documentation.

Keywords

move, shift, transform

Parameters
Name	Type	Description
profile	OBJECT Profile	The profile to translate. This profile is overwritten with the translated profile.
coordinateTranslation	FLOAT	Translation of coordinates.
valueTranslation	FLOAT	Translation of values.

Return values
Name	Type	Description
result	OBJECT Profile	Reference to the translated profile.

Sample

local result = Profile.translateInplace(profile, coordinateTranslation, valueTranslation)

Profile.Curve

Short description

A data type for representing parametric curves and functions such as polynomial and exponential functions. Different families of functions are available.

Keywords

analytic, exponential, fitting, function, gauss, line, parametric, trend, polynomial

Overview

clone(), createExponential(), createGaussian(), createLine(), createPolynomial(), getDerivative(), getExponentialParameters(), getGaussianParameters(), getLineParameters(), getPolynomialParameters(), getType(), scale(), scaleInplace(), toProfile(), toString(), translate(), translateInplace()

Functions

clone()

Short description

Create an independent copy of this curve.

Keywords

copy

Parameters
Name	Type	Description
inputCurve	CONST_OBJECT Profile.Curve	The curve to clone.

Return values
Name	Type	Description
outputCurve	OBJECT Profile.Curve	The new copy.

Sample

outputCurve = Profile.Curve.clone(inputCurve)

createExponential()

Short description

Create an exponential curve. f(x) = scale*exp(exponent*x) + offset.

Parameters
Name	Type	Description
scale	FLOAT	Linear scaling of the curve.
exponent	FLOAT	Exponent.
offset	FLOAT	Constant offset of the curve.

Return values
Name	Type	Description
expCurve	OBJECT Profile.Curve	The created exponential curve.

Sample

expCurve = Profile.Curve.createExponential(scale, exponent, offset)

createGaussian()

Short description

Create a Gaussian curve. f(x) = scale*exp(-x-mean)^2) / (2*sigma^2 + offset.

Parameters
Name	Type	Description
scale	FLOAT	Linear scaling of the curve.
mean	FLOAT	Mean (symmetry axis of generated function).
sigma	FLOAT	Standard deviation (width of lobe).
offset	FLOAT	Constant offset of the curve.

Return values
Name	Type	Description
gaussCurve	OBJECT Profile.Curve	The created Gaussian curve.

Sample

gaussCurve = Profile.Curve.createGaussian(scale, mean, sigma, offset)

createLine()

Short description

Create a line f(x) = offset + slope*x with the specified offset and slope. This is equivalent to creating a first order polynomial.

See also

Profile.Curve.createPolynomial

Parameters
Name	Type	Description
offset	FLOAT	Offset of line, value at x = 0.
slope	FLOAT	Slope of line, dy/dx.

Return values
Name	Type	Description
line	OBJECT Profile.Curve	The created line.

Sample

line = Profile.Curve.createLine(offset, slope)

createPolynomial()

Short description

Create a polynomial curve with the specified coefficients. The first coefficient is the constant term, the second is for the linear term and so on.

See also

Profile.Curve.createLine

Parameters
Name	Type	Description
coefficients	FLOAT	Coefficients a, b, c, … in a + bx + cx^2 + …

Return values
Name	Type	Description
polyCurve	OBJECT Profile.Curve	The created polynomial curve.

Sample

polyCurve = Profile.Curve.createPolynomial(coefficients)

getDerivative()

Short description

Return the derivative of the curve if it can be expressed by any available curve type.

Parameters
Name	Type	Description
curve	CONST_OBJECT Profile.Curve	The curve to take the derivative of.

Return values
Name	Type	Description
derivativeCurve	OBJECT Profile.Curve	The derivative of the curve.

Sample

derivativeCurve = Profile.Curve.getDerivative(curve)

getExponentialParameters()

Short description

Returns the parameters of an exponential curve, f(x) = scale*exp(exponent*x) + offset.

See also

Profile.CurveFitter.fitExponential

Parameters
Name	Type	Description
expCurve	CONST_OBJECT Profile.Curve	The exponential curve.

Return values
Name	Type	Description
scale	FLOAT	Linear scaling of the curve.
exponent	FLOAT	Exponent.
offset	FLOAT	Constant offset of the curve.

Sample

scale, exponent, offset = Profile.Curve.getExponentialParameters(expCurve)

getGaussianParameters()

Short description

Returns the parameters of a Gaussian curve, f(x) = scale*exp(-x-mean)^2) / (2*sigma^2 + offset.

See also

Profile.CurveFitter.fitGaussian

Parameters
Name	Type	Description
gaussCurve	CONST_OBJECT Profile.Curve	The Gaussian curve.

Return values
Name	Type	Description
scale	FLOAT	Linear scaling of the curve.
mean	FLOAT	Mean (symmetry axis of generated function).
sigma	FLOAT	Standard deviation (width of lobe).
offset	FLOAT	Constant offset of the curve.

Sample

scale, mean, sigma, offset = Profile.Curve.getGaussianParameters(gaussCurve)

getLineParameters()

Short description

Returns the offset and slope of a line.

See also

Profile.CurveFitter.fitLine

Parameters
Name	Type	Description
line	CONST_OBJECT Profile.Curve	The line.

Return values
Name	Type	Description
offset	FLOAT	Offset of line, value at x = 0.
slope	FLOAT	Slope of line, dy/dx.

Sample

offset, slope = Profile.Curve.getLineParameters(line)

getPolynomialParameters()

Short description

Returns the coefficients of a polynomial curve. The first coefficient is the constant term, the second is for the linear term and so on.

See also

Profile.CurveFitter.fitPolynomial

Parameters
Name	Type	Description
polyCurve	CONST_OBJECT Profile.Curve	The polynomial curve.

Return values
Name	Type	Description
coefficients	FLOAT	Coefficients a, b, c, … in a + bx + cx^2 + …

Sample

coefficients = Profile.Curve.getPolynomialParameters(polyCurve)

getType()

Short description

Return the type of function that represents the curve.

Parameters
Name	Type	Description
curve	CONST_OBJECT Profile.Curve	The curve to check.

Return values
Name	Type	Description
curveType	ENUM CurveType	The curve type.

Sample

curveType = Profile.Curve.getType(curve)

scale()

Short description

Scales a curve in the coordinate dimension and/or in the value dimension by recalculating curve parameters, centered around the origin. A nil value indicates unit scaling in the corresponding dimension.

Keywords

multiply, resize, transform

Parameters
Name	Type	Description
curve	CONST_OBJECT Profile.Curve	The source curve.
coordinateScale	FLOAT	Scale factor of coordinates.
valueScale	FLOAT	Scale factor of values.

Return values
Name	Type	Description
result	OBJECT Profile.Curve	Scaled curve.

Sample

local result = Profile.Curve.scale(curve, coordinateScale, valueScale)

scaleInplace()

Short description

In-place version of scale, see base function for full documentation.

Keywords

multiply, resize, transform

Parameters
Name	Type	Description
curve	OBJECT Profile.Curve	The curve to scale and the scaled curve.
coordinateScale	FLOAT	Scale factor of coordinates.
valueScale	FLOAT	Scale factor of values.

Return values
Name	Type	Description
result	OBJECT Profile.Curve	Reference to the scaled profile.

Sample

local result = Profile.Curve.scaleInplace(curve, coordinateScale, valueScale)

toProfile()

Short description

Evaluate the curve at all points in the reference profile and return as a new profile. The reference profile must have 1D sampling coordinates. For a smoother plot, extra samples may be inserted between the samples of the reference profile. This is controlled by the optional parameter extraSamples.

Parameters
Name	Type	Description
curve	CONST_OBJECT Profile.Curve	Input curve.
referenceProfile	CONST_OBJECT Profile	Reference profile.
extraSamples	INT	This many samples are inserted in the output profile between each two samples of the reference profile. Default is zero.

Return values
Name	Type	Description
curveProfile	OBJECT Profile	The sampled curve as a profile.

Sample

curveProfile = Profile.Curve.toProfile(curve, referenceProfile, extraSamples)

toString()

Short description

Get a human-readable string describing the curve.

Keywords

print, description

Parameters
Name	Type	Description
curve	CONST_OBJECT Profile.Curve	Input curve.

Return values
Name	Type	Description
str	STRING	String description of the curve.

Sample

print(Profile.Curve.toString(curve))

translate()

Short description

Translates a curve in the coordinate dimension and/or in the value dimension by recalculating curve parameters. A nil value indicates no translation in the corresponding dimension.

Keywords

move, shift, transform

Parameters
Name	Type	Description
curve	CONST_OBJECT Profile.Curve	The source curve.
coordinateTranslation	FLOAT	Translation of coordinates.
valueTranslation	FLOAT	Translation of values.

Return values
Name	Type	Description
result	OBJECT Profile.Curve	Translated curve.

Sample

local result = Profile.Curve.translate(curve, coordinateTranslation, valueTranslation)

translateInplace()

Short description

In-place version of translate, see base function for full documentation.

Keywords

move, shift, transform

Parameters
Name	Type	Description
curve	OBJECT Profile.Curve	The curve to translate and the translated curve.
coordinateTranslation	FLOAT	Translation of coordinates.
valueTranslation	FLOAT	Translation of values.

Return values
Name	Type	Description
result	OBJECT Profile.Curve	Reference to the translated profile.

Sample

local result = Profile.Curve.translateInplace(curve, coordinateTranslation, valueTranslation)

Profile.CurveFitter

Short description

For fitting parametric curves and functions to measurements stored in a profile object. Both ordinary least squares fitting (default) and robust fitting using RANSAC are possible.

Keywords

curve, function, least squares, ransac, trend, fitting

Overview

create(), fitExponential(), fitGaussian(), fitLine(), fitPolynomial(), getPoints(), getResiduals(), setFitMode(), setIterations(), setOutlierMargin(), toString()

Functions

create()

Short description

Create a curve fitter with default settings.

Return values
Name	Type	Description
curveFitter	HANDLE	Created curve fitter.

Sample

curveFitter = Profile.CurveFitter.create()

fitExponential()

Short description

Fit an exponential curve to the valid points in a profile.

See also

Profile.Curve.getExponentialParameters

Parameters
Name	Type	Description
curveFitter	HANDLE	Curve fitter to use.
inputProfile	OBJECT Profile	The profile to fit the curve to.

Return values
Name	Type	Description
expCurve	OBJECT Profile.Curve	The fitted exponential curve, or nil if fitting failed.

Sample

expCurve = Profile.CurveFitter.fitExponential(curveFitter, inputProfile)

fitGaussian()

Short description

Fit a Gaussian curve to the valid points in a profile. Fitting a Gaussian is quite sensitive to noise and degenerate cases, where the points do not come from a Gaussian function. Using RANSAC robust fitting is recommended as it is much less likely to fail.

See also

Profile.Curve.getGaussianParameters

Parameters
Name	Type	Description
curveFitter	HANDLE	Curve fitter to use.
inputProfile	OBJECT Profile	The profile to fit the curve to.

Return values
Name	Type	Description
gaussCurve	OBJECT Profile.Curve	The fitted Gaussian curve, or nil if fitting failed.

Sample

gaussCurve = Profile.CurveFitter.fitGaussian(curveFitter, inputProfile)

fitLine()

Short description

Fit a line to the valid points in a profile. Equivalent to fitting a first order polynomial. The coordinate system of the profile must be 1D.

See also

Profile.Curve.getLineParameters

Parameters
Name	Type	Description
curveFitter	HANDLE	Curve fitter to use.
inputProfile	OBJECT Profile	The profile to fit the curve to.

Return values
Name	Type	Description
line	OBJECT Profile.Curve	The fitted line.

Sample

line = Profile.CurveFitter.fitLine(curveFitter, inputProfile)

fitPolynomial()

Short description

Fit a polynomial curve to the valid points in a profile. Set the order parameter to zero for a constant function, one for a line, two for a quadratic function and so on. The coordinate system of the profile must be 1D.

See also

Profile.Curve.getPolynomialParameters

Parameters
Name	Type	Description
curveFitter	HANDLE	Curve fitter to use.
inputProfile	OBJECT Profile	The profile to fit the curve to.
order	INT	Order of the polynomial to fit.

Return values
Name	Type	Description
polyCurve	OBJECT Profile.Curve	The fitted polynomial curve, or nil if fitting failed.

Sample

polyCurve = Profile.CurveFitter.fitPolynomial(curveFitter, inputProfile, order)

getPoints()

Short description

Get the edge points used in the last call to any of the fitting functions. Intended for visualization, parameter tuning and debugging. Two lists are returned, the first contains all points that were used to fit the final curve. The second list contains all valid points in the profile not used for fitting the shape. For the least squares method, all points are always in the first list.

Parameters
Name	Type	Description
curveFitter	HANDLE	Curve fitter to use.

Return values
Name	Type	Description
inlierPoints	OBJECT Point	Points used for the final fitting of the curve, a subset of the valid points in the profile.
outlierPoints	OBJECT Point	Points not used for the final fitting, the remainder of the valid points.

Sample

inlierPoints, outlierPoints = Profile.CurveFitter.getPoints(curveFitter)

getResiduals()

Short description

Get fitting information from the last successful curve fit. Values are related to the inliers as can be obtained from getPoints.

Parameters
Name	Type	Description
curveFitter	HANDLE	Curve fitter to use.

Return values
Name	Type	Description
rmsError	FLOAT	The root mean squared error among the inliers.
inlierRatio	FLOAT	Ratio of inlier points to the total number of points, between 0 and 1.
inlierResiduals	FLOAT	Signed residuals for all inliers, the difference between the curve value and the profile value at each position.
outlierResiduals	FLOAT	Signed residuals for all outliers, the difference between the curve value and the profile value at each position.

Sample

rmsError, inlierRatio, inlierResiduals, outlierResiduals = Profile.CurveFitter.getResiduals(curveFitter)

setFitMode()

Short description

Set the fitting mode. The following modes are supported: - LEASTSQUARES uses all points. This is fast and easy, but can produce poor results if there are points that do not belong to the curve to be fitted (default). - RANSAC is a robust method with outlier rejection. Using this method, outlier points can be ignored. This mode requires an outlier margin to be set by setOutlierMargin. The number of iterations can be set by setIterations.

Keywords

ransac, robust, least squares

See also

Profile.CurveFitter.getFitMode

Parameters
Name	Type	Description
curveFitter	HANDLE	Curve fitter to use.
fitMode	ENUM Profile.CurveFitter.CurveFitMode	Fitting mode to use.

Sample

Profile.CurveFitter.setFitMode(curveFitter, fitMode)

setIterations()

Short description

Set the maximum number of iterations in the fitting step. A higher value makes the fitting more accurate, but consumes more computation time. The default is 1000 iterations.

See also

Profile.CurveFitter.getIterations

Parameters
Name	Type	Description
curveFitter	HANDLE	Curve fitter to use.
iterations	INT	Number of iterations.

Sample

Profile.CurveFitter.setIterations(curveFitter, iterations)

setOutlierMargin()

Short description

Set the outlier margin when using RANSAC robust fitting mode. The interpretation of the margin parameter depends on the fitting mode parameter: - RANK: the outlier margin is interpreted as a rank measure, defining the rate of points to include. In this case, the margin must be in the range (0.0, 1.0). A rank margin of 0.7 means that only the best fitting 70% of all points will be included, and the rest ignored. - ABSOLUTE: the outlier margin is defined in absolute world units. Any points further away from the fitted curve than this margin will be ignored. In general a larger value means that more points are included in the fitting, which can improve the accuracy as long as all included points are valid. A smaller value makes the algorithm reject more points, which can increases robustness against single erroneous points. The default is an RANK margin of 0.5.

Parameters
Name	Type	Description
curveFitter	HANDLE	Curve fitter to use.
margin	FLOAT	Outlier margin, expressed in world coordinate units or as a rank measure, depending on the marginType.
marginType	ENUM Profile.CurveFitter.CurveOutlierMarginType	Outlier margin type.

Sample

Profile.CurveFitter.setOutlierMargin(curveFitter, margin, marginType)

toString()

Short description

Get a human-readable string describing the curve fitter.

Keywords

print, description

Parameters
Name	Type	Description
curve	CONST_OBJECT Profile.CurveFitter	Input curve fitter.

Return values
Name	Type	Description
str	STRING	String description of the curve.

Sample

print(Profile.CurveFitter.toString(curve))

Profile.Log

Short description

Object for incremental logging and statistics of measurements, typically in form of timeseries. Measurements are added one-by-one and statistical properties such as mean, standard deviation, min, max and histogram are updated incrementally. Thus, statistics over infinitely long timeseries can be recorded. There is an option to keep a vector of the most recently added values, for example for plotting reasons. There is also an option to maintain vectors of historic statistics (mean, min, max, std) over time intervals that is dynamically compressed (downsampled) when the vectors get full, so as to be able to calculate statistics over intervals in very long timeseries. Some properties are off by default, such as histogram updating and recent and historic value logging. These options need to be enabled explicitly using the dedicated functions for this, e.g., enableHistogram(). It is possible to save and load Profile.Log instances using the Object.save() and Object.load() functions.

Keywords

analytics, average, histogram, historic, incremental, infinite, logging, mean, record, standard deviation, std, time series, timeseries, statistics

Overview

addValue(), create(), enableHistogram(), enableHistoricStatistics(), enableRecentValues(), getCount(), getHistogram(), getHistoricMax(), getHistoricMean(), getHistoricMin(), getHistoricPeriod(), getHistoricStdDev(), getMax(), getMean(), getMin(), getRecentValues(), getStdDev(), toString()

Functions

addValue()

Short description

Add value(s). Values can be added one-by-one, in vector form to add several values at once, or in Profile form.

Parameters
Name	Type	Description
log	OBJECT [API:DataFormat:]	The log object.
value	CONST_AUTO	Value(s) to add. Can be a single float, a vector of floats, or a Profile object.
coordinate	CONST_AUTO	Optional coordinate of the added value(s), length and type must match the value input.

create()

Short description

Create new Log object

Return values
Name	Type	Description
log	OBJECT Profile.Log	The Log object.

enableHistogram()

Short description

Enables the histogram feature to incrementally maintain a histogram of all logged values.

Parameters
Name	Type	Description
log	OBJECT [API:DataFormat:]	The log object.
minValue	FLOAT	Center coordinate of the lowest bin.
maxValue	FLOAT	Center coordinate of the highest bin.
binsCount	INT	Number of bins.

enableHistoricStatistics()

Short description

Enables the historic statistics feature. Vectors of historic statistics (mean, max, min, std) over time periods are maintained. When the vectors gets full they are compressed (downsampled) a factor 2, and thus the time period represented also increases a factor 2. With this feature one can gather statistics over intervals in very long time series.

Parameters
Name	Type	Description
log	OBJECT [API:DataFormat:]	The log object.
periodCount	INT	Number of periods to keep. This is also the maximum size of the periods. Must be equal or larger than 10.

enableRecentValues()

Short description

Enables storage of recent values. The size of the vector to maintain needs to be specified.

Parameters
Name	Type	Description
log	OBJECT [API:DataFormat:]	The log object.
count	INT	The number of stored values.

getCount()

Short description

Get total number of values added to the log.

Parameters
Name	Type	Description
log	CONST_OBJECT [API:DataFormat:]	The log object.

Return values
Name	Type	Description
count	INT	Number of added values.

getHistogram()

Short description

Get the histogram represented as a Profile object. The histogram feature must be enabled.

Parameters
Name	Type	Description
log	CONST_OBJECT [API:DataFormat:]	The log object.

Return values
Name	Type	Description
recent	OBJECT Profile	Histogram with the frequency in the values and bin centers as coordinates.

getHistoricMax()

Short description

Get the maximum of the values in each historic period.

Parameters
Name	Type	Description
log	CONST_OBJECT [API:DataFormat:]	The log object.

Return values
Name	Type	Description
max	OBJECT Profile	Profile with the maximum of the values in the periods.

getHistoricMean()

Short description

Get the mean of the values in each historic period.

Parameters
Name	Type	Description
log	CONST_OBJECT [API:DataFormat:]	The log object.

Return values
Name	Type	Description
mean	OBJECT Profile	Profile with the mean of the values in the periods.

getHistoricMin()

Short description

Get the minimum of the values in each historic period.

Parameters
Name	Type	Description
log	CONST_OBJECT [API:DataFormat:]	The log object.

Return values
Name	Type	Description
min	OBJECT Profile	Profile with the minimum of the values in the periods.

getHistoricPeriod()

Short description

Get number of values in each historic period.

Parameters
Name	Type	Description
log	CONST_OBJECT [API:DataFormat:]	The log object.

Return values
Name	Type	Description
count	INT	Number of stored values per historic period.

getHistoricStdDev()

Short description

Get the standard deviation in each historic period.

Parameters
Name	Type	Description
log	CONST_OBJECT [API:DataFormat:]	The log object.

Return values
Name	Type	Description
stddev	OBJECT Profile	Profile with the standard deviations of the values in the periods.

getMax()

Short description

Get the minimum value and its coordinate over all values added to the log.

Parameters
Name	Type	Description
log	CONST_OBJECT [API:DataFormat:]	The log object.

Return values
Name	Type	Description
max	FLOAT	Maximum value.
coord	FLOAT	Coordinate of maximum value.

getMean()

Short description

Get the mean/average over all values added to the log.

Parameters
Name	Type	Description
log	CONST_OBJECT [API:DataFormat:]	The log object.

Return values
Name	Type	Description
mean	FLOAT	Mean value.

getMin()

Short description

Get the minimum value and its coordinate over all values added to the log.

Parameters
Name	Type	Description
log	CONST_OBJECT [API:DataFormat:]	The log object.

Return values
Name	Type	Description
min	FLOAT	Minimum value.
coord	FLOAT	Coordinate of minumum value.

getRecentValues()

Short description

Get the vector of recent values as a Profile object. Recent values must be enabled.

Parameters
Name	Type	Description
log	CONST_OBJECT [API:DataFormat:]	The log object.

Return values
Name	Type	Description
recent	OBJECT Profile	Profile with the latest values and coordinates.

getStdDev()

Short description

Get the standard deviation over all values added to the log.

Parameters
Name	Type	Description
log	CONST_OBJECT [API:DataFormat:]	The log object.

Return values
Name	Type	Description
stddev	FLOAT	Standard deviation.

toString()

Short description

Get a string describing the log.

Keywords

print, description

Parameters
Name	Type	Description
curve	CONST_OBJECT Profile.Log	Input log.

Return values
Name	Type	Description
str	STRING	String description of the log.

Sample

print(Profile.Log.toString(curve))

Profile.Matching

Short description

Functions for matching and locating patterns in profiles based on different shape models such as sample pattern models.

Keywords

detection, feature, pattern, localization

Profile.Matching.PatternMatcher

Short description

Finds patterns in a profile based on template matching. Teach a pattern from a reference profile and call match to find the location of the same shape in a live profile.

Overview

create(), getAllFoundMatches(), match(), setMaximumInvalidValues(), teach(), toString()

Functions

create()

Short description

Creates a new matcher for 1D pattern localization in profiles.

Return values
Name	Type	Description
locator	HANDLE	The new instance.

Sample

locator = Profile.Matching.PatternMatcher.create()

getAllFoundMatches()

Short description

Get vector with all found matches sorted with descending score. A match is a local maximum in the comparison mode evaluation.

See also

Profile.Matching.PatternMatcher.match

Parameters
Name	Type	Description
locator	HANDLE	The instance to use.

Return values
Name	Type	Description
positions	FLOAT	Positions (indices) of found matches.
scores	FLOAT	scores.

Sample

 positions, scores = Profile.Matching.PatternMatcher.getAllFoundMatches(locator)

match()

Short description

Finds a pattern in a live profile by matching with the teach model. A teach call must be made first. The output is the position (index) of the best found match, with the origin for the template in the first element. Only one instance of a pattern is returned, the one with the strongest match score. However, after a match call, a vector of all match candidates can be obtained using the getAllFoundMatches function. A match score in the range [0.0, 1.0] is returned indicating the score strength. Depending on the comparison mode (selected in teach call), the score is calculated as follows: SAD: The best (lowest) SAD_min difference is found. The score is calculated as max(1.0 - SAD_min/(max_value - min_value), 0.0), where max value and min_value are the maximum and minimum values within the teach profile. This gives a score value that is 1.0 if the teach and live are identical, and 0.0 if for example all samples in the live profile deviates with at least the teach range. XCORRNORM: The best (highest) correlation coefficient XCORRNORM_max is found. The score is calculated as max(XCORRNORM_max, 0.0) to give as score 1.0 if the teach and match profiles correlate perfectly. Coordinate system handling: The coordinates are not considered in this function. Invalid flag usage: Invalid samples are excluded from the matching but can affect the score measure.

Keywords

locate, find

Parameters
Name	Type	Description
locator	HANDLE	The matcher instance to use.
liveProfile	CONST_OBJECT Profile	The live profile to find the shape in.

Return values
Name	Type	Description
position	FLOAT	Position (index) of the start of detected pattern in the live profile. Nil is returned if the match process failed.
matchScore	FLOAT	A score between 0.0 and 1.0 for the best detected pattern. High score means good match.

Sample

position, matchScore = Profile.Matching.PatternMatcher.match(locator, liveProfile)

setMaximumInvalidValues()

Short description

Set maximum number of invalid samples in the live profile, which overlaps the teach profile. Thus, matches where the teach profile overlaps with too many invalid samples in the live profile are discarded. The default value if this parameter is to allow any number of invalid values.

Parameters
Name	Type	Description
locator	HANDLE	The instance to use.
maxInvalidValues	INT	Maximum number of invalid samples.

Sample

 Profile.Matching.PatternMatcher.setMaximumInvalidValues(locator, maxInvalidValues)

teach()

Short description

Teaches a pattern model from a template profile. The template profile is typically shorter than the profile later used for matching in, e.g., it is a cropped version of a reference profile containing just the pattern of interest. Samples can be excluded from the teach model by setting the valid flags of the corresponding samples to invalid. Note that the teach profile must contain atleast 5 valid samples. There are two modes later used in the match call to determine how the teach pattern is compared to a profile to match in: SAD: Sum of absolute differences. A match score is calculated based on the sum of the absolute differences between the teach profile and the match profile. XCORRNORM: Cross correlation with normalization. A match score is calculated based on a cross-correlation operation. This mode is insensitive to different scalings and mean levels between the teach and match profiles.

Keywords

template, pattern

Parameters
Name	Type	Description
locator	HANDLE	The instance to use.
teachProfile	CONST_OBJECT Profile	The teach profile.
comparisonMode	ENUM ComparisonMode	Comparison method XCORRNORM or SAD. Default: XCORRNORM.

Return values
Name	Type	Description
success	BOOL	True if teach succeeded.

Sample

 success = Profile.Matching.PatternMatcher.teach(locator, teachProfile, matchMode)

toString()

Short description

Get a human-readable string describing the pattern matcher.

Keywords

print, description

Parameters
Name	Type	Description
locator	CONST_OBJECT Profile.Matching.PatternMatcher	Input pattern matcher.

Return values
Name	Type	Description
str	STRING	String description of the pattern matcher.

Sample

print(Profile.Matching.PatternMatcher.toString(patternMatcher))

Script

Short description

Provides general functions to communicate with the system and other Apps. E.g. functions to register script functions/-events to the system, in order to call them from other CROWNS. These functions are only available from scripting!

Overview

callFunction(), callFunctionAsync(), deregister(), disableGarbageCollectionByEngine(), isEventRegistered(), isServedAsEvent(), isServedAsFunction(), notifyEvent(), register(), releaseObject(), serveEvent(), serveFunction(), sleep(), startScript()

Functions

callFunction()

Short description

Call a CROWN function generically by name from a script context. This is useful if the function name is set dynamically and not known. This call blocks until the function has run and returns its return-values.

Parameters
Name	Type	Description
funcName	STRING	The function name of the function to call
param1	AUTO	First parameter for the function call (optional)
param2	AUTO	second parameter for the function call (optional)
param3	AUTO	third parameter for the function call (optional)
param4	AUTO	fourth parameter for the function call (optional)
param5	AUTO	fifth parameter for the function call (optional)
param6	AUTO	sixth parameter for the function call (optional)
param7	AUTO	seventh parameter for the function call (optional)

Return values
Name	Type	Description
success	BOOL	True if the function has been called successfully, false if function name was not a valid served function or wrong parameters passed to call the function.
result1	AUTO	First result of the function call (optional)
result2	AUTO	second result of the function call (optional)
result3	AUTO	third result of the function call (optional)
result4	AUTO	fourth result of the function call (optional)
result5	AUTO	fifth result of the function call (optional)
result6	AUTO	sixth result of the function call (optional)
result7	AUTO	seventh result of the function call (optional)

Sample

success, ret1, ret2 = Script.callFunction("theFuncName", param1, param2)

callFunctionAsync()

Short description

Call a CROWN function generically by name from a script context without waiting for the return value. This is useful if the function name is set dynamically and not known. This call does not block if the function is implemented in another thread/script and return-values are discarded. The call isn’t guaranteed to be run async: It depends on the implementation of the calling function.

Parameters
Name	Type	Description
funcName	STRING	The function name of the function to call
param1	AUTO	First parameter for the function call (optional)
param2	AUTO	second parameter for the function call (optional)
param3	AUTO	third parameter for the function call (optional)
param4	AUTO	fourth parameter for the function call (optional)
param5	AUTO	fifth parameter for the function call (optional)
param6	AUTO	sixth parameter for the function call (optional)
param7	AUTO	seventh parameter for the function call (optional)

Return values
Name	Type	Description
success	BOOL	True if the function has been called successfully, false if function name was not a valid served function

Sample

success = Script.callFunctionAsync("theFuncName", param1, param2)

deregister()

Short description

Deregisters a function from an event, which was registered at the event before. Deregistration are automatically done on script destruction.

Parameters
Name	Type	Description
eventName	STRING	The event name to deregister from.
consumer	STRING	The function name which was used for registering.

Return values
Name	Type	Description
success	BOOL	Returns true if successfully deregistered.

Sample

Script.deregister("Crown.Event","MyFunction")

disableGarbageCollectionByEngine()

Short description

Disables the automatic collectgarbage() calls by the engine for the current Lua script interpreter which are done after each script callback. Per default there is a full garbage collector run done on leaving the interpreter, to avoid non-deterministic behaviour due to no released CROWN objects from the interpreter. This disableGarbageCollectionByEngine()-function can be called at the beginning of a script in global scope to disable the automatic collectgarbage()-calls. If this function is used, the user has to know how lua garbage collection works and needs to take care by himself of the garbage collector settings of the Lua interpreter. The user also can manually release objects and handles using the function "Script.releaseObject". For easier usage of disabled engine garbage collection, this function also changes the garbagecollector settings to the following more aggressive settings: - collectgarbage("setpause", 100) — means "no pause". Lua default is 200 which is that the collection cycle starts only when the used memory is doubled. - collectgarbage("setstepmul", 400) — increases the work which each incremental step does. Lua default is 200. To tune the settings even more for your application, please read more about garbage collector in lua documentation. Basic suggestion: If the memory increases in your application and memory isn’t collected fast enough, increase the "setstepmul" to larger values than 400.

Sample

Script.disableGarbageCollectionByEngine()

isEventRegistered()

Short description

Returns true if a served event has minimum one registration active. Only works with events which were served by this script using the Script.serveEvent-function.

Parameters
Name	Type	Description
localEventName	STRING	Name of the event which is to be notified. The event needs to match the localEventName used in ServeEvent-function.

Return values
Name	Type	Description
success	BOOL	True if there is minimum one registration active.
registrationCount	INT	If there is a registration, this value contains the number of registrations, otherwise nil.

Sample

Script.isEventRegistered("MyEvent")

isServedAsEvent()

Short description

Returns true if the specified event name is served anywhere in the CROWN framework. This is especially useful when registering to dynamic events and checking before if the event is still served and available.

Parameters
Name	Type	Description
eventName	STRING	The event name which should be checked

Return values
Name	Type	Description
isServed	BOOL	True if the specified event name is currently served as CROWN event in the framework

isServedAsFunction()

Short description

Returns true if the specified function name is served anywhere in the CROWN framework. This is especially useful when calling dynamic functions and checking before if the function is still served and available.

Parameters
Name	Type	Description
funcName	STRING	The function name which should be checked

Return values
Name	Type	Description
isServed	BOOL	True if the specified function name is currently served as CROWN function in the framework

notifyEvent()

Short description

Use to notify an event which was served by the Script.serveEvent function by this app. Add any parameter to notify along with this event to the argument list.

Parameters
Name	Type	Description
localEventName	STRING	Name of the event which is to be notified. The event needs to match the localEventName used in ServeEvent-function.
parameters	AUTO	Parameters to notify.

Return values
Name	Type	Description
success	BOOL	True if successfully notified, false otherwise

Sample

Script.notifyEvent("MyEvent", value1, value2)

register()

Short description

Registers a function to an event. Registrations are possible only once per function and event. Further register calls for same combination return false. Registrations are always successfully done although the event might not be served already. In future the event still could get served and fired. If successfully registered there is a second return value added which indicates if the registered event is currently served by someone. This is useful to verify the wiring of an application. All calls to the registered function are executed sequentially in the context of the registering application. Execution of the event notifier is not blocked and event callback calls are queued up at the registered application. If there is a function pointer used for registering, the execution of the function always happens in the current script context (pay attention if registering another apps functions to use register function by name).

Parameters
Name	Type	Description
eventName	STRING	The event name to register to.
consumer	STRING	Name of the function to be called if the event occurs.

Return values
Name	Type	Description
success	BOOL	Returns true if successfully registered. False if the function is already registered on that event.
eventServed	BOOL	If registration was successful, this second parameter is added. True if the registered event is really served by someone.

Sample

Script.register("Crown.Event","MyFunction")

releaseObject()

Short description

Explicitly releases an object or handle from the script. If there is no one other holding a reference to the object, it is freed. This is useful if the user does not want to wait until the garbage collector releases it but does it at an explicit location.

Parameters
Name	Type	Description
objectToRelease	AUTO	The object(s) or handle(s) to release

Sample

Script.releaseObject(obj)

serveEvent()

Short description

Call to publish an event, so other apps can register on. The event must be specified in the app manifest over the AppStudio AppProperties Serves-tab.

Parameters
Name	Type	Description
crownEventName	STRING	The name used in the CROWN system. The app name must be prefixed to have a full qualified CROWN name (e.g. 'MyApp.MyEvent')
localEventName	STRING	Name of the event inside the lua script. Use this name for the Script.notifyEvent() function.
parameterListType	STRING	DEPRECATED! Not needed to be specified if the event is declared in the manifest over AppStudio AppProperties Serves-tab! Comma separated parameter definition list, e.g.: 'bool,string,int,object'. Types match the crown types. Syntax for one type: 'qualifier typename:multiplicity:alias'

Return values
Name	Type	Description
success	BOOL	True if successfully served, false otherwise

Sample

Script.serveEvent("MyApp.MyEvent", "MyEvent")

serveFunction()

Short description

Use to publish a lua function, so it can be called from other Apps. The function must be specified in the app manifest over the AppStudio AppProperties Serves-tab. All calls of the served function are executed sequentially in the context of the serving application. Execution of the caller is deferred until the function returns. There is no need for additional synchronization.

Parameters
Name	Type	Description
crownFunctionName	STRING	The name used in the CROWN system. The app name must be prefixed to have a full qualified CROWN name (e.g. 'MyApp.MyFunc')
localFunctionName	STRING	Name of the function inside the lua script, e.g. 'MyFunc'
parameterTypeList	STRING	DEPRECATED! Not needed to be specified if the function is declared in the manifest over AppStudio AppProperties Serves-tab! Comma separated parameter definition list, e.g.: 'bool,string,int,object'. Types match the crown types. Syntax for one type: 'qualifier typename:multiplicity:alias'
returnTypeList	STRING	DEPRECATED! Not needed to be specified if the function is declared in the manifest over AppStudio AppProperties Serves-tab! Comma separated return value definition list, e.g.: 'bool,string,int,object'. Types match the crown types. Syntax for one type: 'qualifier typename:multiplicity:alias'

Return values
Name	Type	Description
success	BOOL	True if successfully served, false otherwise

Sample

Script.serveFunction("MyApp.MyFunction", "MyFunction")

sleep()

Short description

Stops the execution of the interpreter at the given position and releases the processor. This can be used to delay the script at a given position. The usage of this function should be avoided for released applications but can be useful for testing. The script can be stopped also if it is sleeping at this position. During sleeping the lua script cannot handle events or other function calls. They are queued up and will be handled if the caller of this sleep returns from the script.

Parameters
Name	Type	Description
sleepTimeMs	INT	The time in milliseconds to sleep. The effective sleept time could be higher.

Sample

Script.sleep(50)

startScript()

Short description

Starts a new script with specified filename in a new interpreter, running in a new task context. This function is used to run several script tasks and interpreters inside a single app. One example where this is useful is if there are long-running blocking function calls, but the app should still stay responsive to events while these calls are executed. One way to realize this is is to use multiple apps, but using multiple scripts within one app has advantages: There is only one app that needs to be deployed, and the scripts within one app can share common lua code via require. The started scripts can use the CROWN framework to communicate with each other, the same way that communication between separate apps works: Via serving and using of functions and events. The script is started synchronous, so this function blocks until the main script scope of the newly started script has ran. After the main script scope has ran, the started script keeps active in the background and can react to events and functions calls to served functions. The lifetime of the script is bound to the app within it was started. Limitations: - The script file to be started must be located directly in the scripts/ directory of the app, it is not possible to start scripts which are located in a subdirectory. - It is not possible to debug a script that is started with this function in AppStudio directly. A possible workaround is to manually change the startScript() call for the specific script to be debugged to a require() to make it execute directly in the context of the main script of the app.

Parameters
Name	Type	Description
fileName	STRING	The file name of the Lua file which is to be started in a new interpreter. The file extension '.lua' can be omitted. The script file to be started must be located directly in the scripts/ directory of the app, it is not possible to start scripts which are located in a subdirectory.
priority	ENUM Priority	Priority of the task running the new interpreter. The available priority levels are the same as the levels that can be selected for an app in the app properties in AppStudio. The parameter is optional. By default, the priority of the script that calls the function is used. In case of the app main script, this is the app priority.

Return values
Name	Type	Description
success	BOOL	Returns true if the script file could be successfully loaded and started.

Sample

local success = Script.startScript("somescript.lua")

Script.Queue

Short description

Provides functionality to create new call queue. Per default each script has a one single default call queue to which all incoming calls are enqueued as they come in. Separate queues are useful to e.g. increase or decrease the queue priority or limit certain incoming events. The default queue of the script has priority 'MID'. All queues on the same priority are scheduled fair, which means each queue can process one queued call in each cycle. The handle to the queue needs to be held so that the queue stays active. If the handle is lost, the events are enqueued again in the default queue and currently queued events are lost. The limitation of queue sizes and discarding if full with the setMaxQueueSize and setDiscardIfFull functions is only possible, if the call is an event callback. For served function executions the limitation is not possible, because the functions always need to be executable and need a return value.

Overview

clear(), create(), getSize(), setDiscardIfFull(), setFunction(), setMaxQueueSize(), setPriority()

Functions

clear()

Short description

Clears all currently queued calls. This only works for event callbacks and not for function callbacks, because function calls always need a return value. Pay attention that directly during returning from this function there might be events already added again.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use

Sample

Script.Queue.clear(handle)

create()

Short description

Creates a new instance.

Return values
Name	Type	Description
handle	HANDLE	Handle to the new instance

Sample

-- Creates a new queue for the current running script with higher priority:
function myCallback()
end
queueHandle = Script.Queue.create()
queueHandle:setPriority("HIGH")
queueHandle:setFunction(myCallback)
-- Now register the callback at an event:
SomeProvider.register(provHandle, "OnSomeEvent", myCallback)

getSize()

Short description

Returns the current number of queue calls. Pay attention that directly during returning from this function there might be events already added again.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use

Return values
Name	Type	Description
size	INT	The current queue size

Sample

size = Script.Queue.getSize(handle)

setDiscardIfFull()

Short description

Sets the behaviour for adding events to the queue if the queue is full. Per default the oldest element is discarded. To discard the newest to be added element, call this function with parameter true.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use
bDiscardIfFull	BOOL	Set to true to discard the newest item which is currently added instead of discarding the oldest element

Sample

Script.Queue.setDiscardIfFull(handle, true)

setFunction()

Short description

Sets the function(s) which are handled by this queue. After this call, the specified functions are removed from the default script queue and added to this queue. So this call should be done as last call. This can be a lua function reference or local function name, and also be a served function name. To prioritize calls to a function served over Script.serveFunction, the served function name has to be used, and the function needs to be served before this call.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use
function	STRING	The function or array of functions which should be handled by this queue.

Sample

Script.Queue.setFunction(handle, callbackFunc)

setMaxQueueSize()

Short description

Sets the maximum queue size of the call queue. This only works for event callbacks and not for function callbacks, because function calls always need a return value. Per default the queue is set to infinite size (=0). If the max queue size is reached, the oldest element is discarded per default. To change that behaviour use the setDiscardIfFull-Function.

Parameters
Name	Type	Description
handle	HANDLE	The instance to use
maxQueueSize	INT	The max number of events to queue. Per default 0 (=infinite)

Sample

Script.Queue.setMaxQueueSize(handle, 10)

setPriority()

Short description

Sets the relative priority of the queue compared to other queues of the script. Per default the priority MID is set, if this function is not called

Parameters
Name	Type	Description
handle	HANDLE	The instance to use
prio	ENUM Priority	The new priority to set

Sample

Script.Queue.setPriority(handle, "LOW")

SensorData

Short description

Provides access to additional sensor data information like origin and time stamp that is sent along with the actual measurement data.

Overview

getFrameNumber(), getID(), getMetaData(), getName(), getOrigin(), getTimestamp(), toString()

Functions

getFrameNumber()

Short description

Returns the frame number (incremented by one for each measurement).

Parameters
Name	Type	Description
sensordata	CONST_OBJECT SensorData	Handle to the instance.

Return values
Name	Type	Description
frameno	INT	The frame number.

Sample

local frameNumber = SensorData.getFrameNumber(theSensorData)

getID()

Short description

Returns an application specific ID (e.g. object ID).

Parameters
Name	Type	Description
sensordata	CONST_OBJECT SensorData	Handle to the instance.

Return values
Name	Type	Description
id	INT	Returns the ID.

Sample

local id = SensorData.getID(theSensorData)

getMetaData()

Short description

Get the MetaData which is associated with the SensorData object. The MetaData object is optional and can contain dynamically configurable additional SensorData. The 'getMetaData' function returns an object of the type Container. The content can be accessed via the Container API.

Parameters
Name	Type	Description
sensordata	CONST_OBJECT SensorData	Input data to get the MetaData from.

Return values
Name	Type	Description
metadata	OBJECT Container	Optional MetaData object.

Sample

local metaData = SensorData.getMetaData(theSensorData)

getName()

Short description

Returns the component name of the corresponding data object (e.g. DepthImage or GreyImage).

Parameters
Name	Type	Description
sensordata	CONST_OBJECT SensorData	Handle to the instance.

Return values
Name	Type	Description
name	STRING	The component name of the corresponding data object.

Sample

local name = SensorData.getName(theSensorData)

getOrigin()

Short description

Returns the origin (e.g. device name).

Parameters
Name	Type	Description
sensordata	CONST_OBJECT SensorData	Handle to the instance.

Return values
Name	Type	Description
origin	STRING	Returns the data origin.

Sample

local origin = SensorData.getOrigin(theSensorData)

getTimestamp()

Short description

Returns the time stamp (in microseconds).

Parameters
Name	Type	Description
sensordata	CONST_OBJECT SensorData	Handle to the instance.

Return values
Name	Type	Description
timestamp	INT	The time stamp value (in microseconds).

Sample

local timeStamp = SensorData.getTimestamp(theSensorData)

toString()

Short description

Get a string representation of the SensorData.

Parameters
Name	Type	Description
sensordata	CONST_OBJECT SensorData	Input data to get the string representation.

Return values
Name	Type	Description
str	STRING	String representation of the SensorData

Sample

print("SensorData: " .. SensorData.toString(theSensorData))

SerialCom

Short description

Provides raw serial communication access. First a new SerialCom client needs to be created using the create function. Afterwards the baudrate and the other settings need to be done. Then a call to the open-function opens the serial port and transmit calls and OnReceive events are possible. Data could be transmitted to the server using the "transmit" function. Data could be received by a register to the "OnReceive" event or by calling the blocking receive()-function. The transmitted and received data is raw data. It could get automatically framed for transmitting and receiving can be automatically parsed if setting a framing with the "setFraming" function. If a framing is set, there is a fix buffer size of receiving and transmitting which is 10240 bytes per default and can be changed using the setFramingBufferSize()-function. Every data packet which is larger than this will be discarded.

Functions

close()

Short description

Closes the serial handle.

Parameters
Name	Type	Description
ifHandle	HANDLE	Handle to the Serial Communication Interface that has been returned by SerialCom.create().

Sample

SerialCom.close(handle)

create()

Short description

Creates a serial communication interface instance if port exists and not already in use.

Parameters
Name	Type	Description
portName	ENUM SerialPorts	The (device dependent) name of the serial port which should be opened.

Return values
Name	Type	Description
ifHandle	HANDLE	Handle to the Serial Communication Interface that has been returned by SerialCom.create(). Nil if not available or already in use.

Sample

handle = SerialCom.create("SER1")

deregister()

Short description

This function is used to deregister from any registered event of the handle.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
eventname	STRING	The event to deregister from
callback	STRING	The function name which was registered on the event

Return values
Name	Type	Description
success	BOOL	True if successfully deregistered. False if event does not exist or callback wasn’t registered.

isOpened()

Short description

Determine whether the serial port is open or not.

Parameters
Name	Type	Description
ifHandle	HANDLE	Handle to the Serial Communication Interface that has been returned by SerialCom.create().

Return values
Name	Type	Description
isOpen	BOOL	true if the COM port is open, false if not

Sample

isOpen = SerialCom.isOpened(handle)

open()

Short description

Opens the serial connection that has been configured with the set* functions.

Parameters
Name	Type	Description
ifHandle	HANDLE	Handle to the Serial Communication Interface that has been returned by SerialCom.create().

Return values
Name	Type	Description
isOpen	BOOL	Returns true if interface could be opened. If false, the port might be in use already.

Sample

success = SerialCom.open(handle)

receive()

Short description

Receives data from the client with a specified timeout. If timeout is zero then it directly returns. The data could be framed if the "setFraming" function was called before. Incoming data between multiple receive calls is queued per message. There is a fix receive queue size of 10 packets per default and can be changed using the setReceiveQueueSize()-function. More data is discarded.

Parameters
Name	Type	Description
ifHandle	HANDLE	Handle to the Serial Communication Interface that has been returned by SerialCom.create().
timeout	INT	Timeout in ms to wait for received data. 0 is default and means directly return.

Return values
Name	Type	Description
data	BINARY	The data which was received

Sample

data = SerialCom.receive(handle, 5000)

register()

Short description

This function is used to register for any event of the handle.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
eventname	STRING	The event to register to
callback	STRING	The function name to call on the event occurrence

Return values
Name	Type	Description
success	BOOL	True if successfully registered. False if event does not exist.

setBaudRate()

Short description

Sets the baudrate. Default is '57600'.

Parameters
Name	Type	Description
ifHandle	HANDLE	Handle to the Serial Communication Interface that has been returned by SerialCom.create().
baudRate	INT	One of 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200

Sample

SerialCom.setBaudRate(handle, 9600)

setDataBits()

Short description

Sets the number of data bits. Default is '8'.

Parameters
Name	Type	Description
ifHandle	HANDLE	Handle to the Serial Communication Interface that has been returned by SerialCom.create().
dataBits	INT	8 or 7

Sample

SerialCom.setDataBits(handle, 8)

setFlowControl()

Short description

Enables or disables hardware flow control. Default is 'false'.

Parameters
Name	Type	Description
ifHandle	HANDLE	Handle to the Serial Communication Interface that has been returned by SerialCom.create().
enabled	BOOL	true to enable flow control, false to disable

Sample

SerialCom.setFlowControl(handle, false)

setFraming()

Short description

Sets the framing which is to be used. If not set the default framing is no framing (raw byte/packet-wise connection). Framing could be also explicitly disabled by calling this function with 2 empty binary data for rx and tx. One framing part could be maximum size of 9 bytes. If a framing is set, there is a fix buffer size of receiving and transmitting which is 10240 bytes per default and can be changed using the setFramingBufferSize()-function. Every data packet which is larger than this will be discarded. The close and open functions has to be called afterwards so that the setting gets active.

Parameters
Name	Type	Description
handle	HANDLE	Handle to the Serial Communication Interface that has been returned by SerialCom.create().
rxStart	BINARY	Start framing for receiving, could be empty string. Maximum size of 9.
rxStop	BINARY	Stop framing for receiving. If empty then all raw data is received. Maximum size of 9.
txStart	BINARY	Start framing for sending, could be empty string. Maximum size of 9.
txStop	BINARY	Stop framing for sending, could be empty string. Maximum size of 9.

Sample

SerialCom.setFraming(handle, "", "", "", "")

setFramingBufferSize()

Short description

Sets the size of the internal framing parser buffer which is used if there is a rx or tx framing set using the setFraming function. If the rx or tx framing isn’t set, its buffer size has no effect. This size is the maximum size of a packet which can be parsed by the framing. The size is used for start and stop framing. Default is 10240 bytes. The close and open functions have to be called afterwards for activating the setting.

Parameters
Name	Type	Description
handle	HANDLE	Handle to the Serial Communication Interface that has been returned by SerialCom.create().
rxBufSize	INT	The new framing buffer size for framed receiving.
txBufSize	INT	The new framing buffer size for framed transmitting.

Sample

SerialCom.setFramingBufferSize(handle, 21000, 21000)

setHandshake()

Short description

Enables or disables handshake. Default is 'false'.

Parameters
Name	Type	Description
ifHandle	HANDLE	Handle to the Serial Communication Interface that has been returned by SerialCom.create().
enabled	BOOL	true to enable Xon/Xoff handshake, false to disable

Sample

SerialCom.setHandshake(handle, true)

setParity()

Short description

Sets the parity. Default is 'N'.

Parameters
Name	Type	Description
ifHandle	HANDLE	Handle to the Serial Communication Interface that has been returned by SerialCom.create().
parity	CHAR	One of "N", "O", "E", "M", "S" (None, Odd, Even, Mark, Space)

Sample

SerialCom.setParity(handle, "N")

setReceiveQueueSize()

Short description

Sets the internal queue size for the receive()-function. Default is 10 packets and discarding the oldest item and warn if overrun occurs. Set to 0 to disable the queue and receiving from the receive()-function, which also increases performance if only receiving over OnReceive-event.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the UDP socket
queueSize	INT	The new receive queue size.
bDiscardIfFull	BOOL	Set to true to discard the newest item which is currently added instead of discarding the oldest element. Default is false.
warnOverruns	BOOL	Set to false to disable warning on overruns when using the receive()-function. Default is true.

Sample

SerialCom.setReceiveQueueSize(handle, 50)

setStopBits()

Short description

Sets the number of stop bits. Default is '1'.

Parameters
Name	Type	Description
ifHandle	HANDLE	Handle to the Serial Communication Interface that has been returned by SerialCom.create().
stopBits	INT	1 or 2

Sample

SerialCom.setStopBits(handle, 1)

setTermination()

Short description

Enables the internal termination of the serial interface. Default is 'false'.

Parameters
Name	Type	Description
ifHandle	HANDLE	Handle to the Serial Communication Interface that has been returned by SerialCom.create().
terminated	BOOL	true to enable internal termination, false to disable

Sample

SerialCom.setTermination(handle, true)

setType()

Short description

Selects the type of the serial interface. Default is 'RS232'.

Parameters
Name	Type	Description
ifHandle	HANDLE	Handle to the Serial Communication Interface that has been returned by SerialCom.create().
type	ENUM SerialComTypes	Interface type which is available on the device. E.g. 'RS232', 'RS422', 'RS485'

Sample

SerialCom.setType(handle, "RS232")

transmit()

Short description

Transmits the data on the serial handle. If framing is set using the "setFraming" function, then the framing characters are automatically prefixed and suffixed to the transmitted data. Blocks until data has been transmitted.

Parameters
Name	Type	Description
ifHandle	HANDLE	Handle to the Serial Communication Interface that has been returned by SerialCom.create().
data	BINARY	The data which should be sent

Return values
Name	Type	Description
numberOfBytesTransmitted	INT	Number of bytes transmitted; 0 if transmit failed

Sample

SerialCom.transmit(handle, "data to transmit")

Events

OnReceive

Short description

The on receive event which is thrown for every new received data.

Parameters
Name	Type	Description
handle	HANDLE	This is a handle event and must be registered on the handle
data	BINARY	The received data

Shape

Short description

A 2D geometric primitive. A Shape can be one of the geometric types Line, LineSegment, Polyline, Rectangle, Circle, Ellipse, Arc or Sector. The Shape object is represented in mathematical analytical form. Operations such as finding intersection points, distances and transforming the Shape are for this reason efficiently computed. Note when used in context of images: The Shapes are defined in the image world coordinate system, i.e., in world scale (typically millimeters) and not in pixel coordinates. The image world coordinate system is left handed, with the x-axis pointing rightwards and the y-axis pointing downwards, and the origin centered at the upper left pixel. In this coordinate system, positive translations along the y-axis will shift the shape downwards, and positive rotations are clockwise. Thus, this is different compared to usage in a right-handed coordinate system context.

Functions

appendPoint()

Short description

Append a point to a polyline shape.

Parameters
Name	Type	Description
shape	OBJECT Shape	The shape to modify. Must be a polyline shape.
point	CONST_OBJECT Point	2D point to add.

Sample

Shape.appendPoint(polyline, Point.create(x, y))

clone()

Short description

Create an independent copy of this shape. If the input is a vector of shapes, the output is a vector of shapes.

Parameters
Name	Type	Description
inputShape	CONST_OBJECT Shape	The shape to clone.

Return values
Name	Type	Description
outputShape	OBJECT Shape	The new copy.

Sample

outputShape = Shape.clone(inputShape)

contains()

Short description

Check if the input point is contained within the enclosed area of the given shape. Always returns false if the shape is not closed. If more than one shape is provided true is returned if the point is inside any of the shapes. If more than one point is provided a vector is returned with one value for each input point.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape	Closed shape enclosing an area
point	CONST_OBJECT Point	Point (2D) to check if contained within the area

Return values
Name	Type	Description
isInside	BOOL	True if the point is contained within the enclosed area, false if not

Sample

isInside = Shape.contains(shape, point)

createArc()

Short description

Create an arc shape (part of a circle). Radius and deltaAngle must be non-negative. By providing vectors of centers, radii, angles and delta angle several arcs can be created. All vectors must be of equal length.

See also

Shape.getArcParameters

Parameters
Name	Type	Description
center	CONST_OBJECT Point	Center point (2D) of the arc. Can also be a vector of center points to create several arcs.
radius	FLOAT	Arc radius. Can also be a vector of radii to create several arcs.
angle	FLOAT	Angle where the arc starts, in radians. Can also be a vector of angles to create several arcs.
deltaAngle	FLOAT	The angular length of the arc, in radians. Can also be a vector of delta angles to create several sectarcsors.

Return values
Name	Type	Description
arc	OBJECT Shape	The created arc, or vector of arcs for for vector input.

Sample

arc = Shape.createArc(centerPoint, radius, angle, deltaAngle)

createCircle()

Short description

Create circle shape(s). By providing vectors of centers and radii, several circles can be created. All vectors must be of equal length.

Parameters
Name	Type	Description
center	CONST_OBJECT Point	A single 2D Point or a vector of points. If the input is a vector, a vector of circles is created.
radius	FLOAT	Circle radius. Must be non-negative. Can also be a vector to create several circles.

Return values
Name	Type	Description
circle	OBJECT Shape	The created circle or vector of circles.

Sample

circle = Shape.createCircle(centerPoint, radius)

createEllipse()

Short description

Create an ellipse shape. Radii must be non-negative. By providing vectors of centers, radiusX, radiusY and rotation, several ellipses can be created. All vectors must be of equal length.

Parameters
Name	Type	Description
center	CONST_OBJECT Point	Center point (2D). Can also be a vector of centre points to create several ellipses.
radiusX	FLOAT	Radius along the x axis (before rotation). Can also be a vector of radii to create several ellipses.
radiusY	FLOAT	Radius along the y axis (before rotation). Can also be a vector of radii to create several ellipses.
rotation	FLOAT	Ellipse rotation in radians. Can also be a vector of rotations to create several ellipses. A positive rotation rotates the x-axis towards the y-axis. Note that when used as region for an image, the image has a left-hand system with the y-axis pointing downwards, in which a positive rotation means a clockwise direction.

Return values
Name	Type	Description
ellipse	OBJECT Shape	The created ellipse, or vector of ellipses for for vector input.

Sample

ellipse = Shape.createEllipse(centerPoint, radiusX, radiusY, rotation)

createLine()

Short description

Create an infinite line shape that connects (and extends beyond) two given points. The points must not be the same. By providing vectors of end-points, several infinite lines can be created. The vectors must be of equal length.

Parameters
Name	Type	Description
point1	CONST_OBJECT Point	A point (2D) on the line. Can also be a vector of points to create several lines.
point2	CONST_OBJECT Point	Another point (2D) on the line. Can also be a vector of points to create several lines.

Return values
Name	Type	Description
line	OBJECT Shape	The created line, or vector of lines for for vector input.

Sample

line = Shape.createLine(point1, point2)

createLineSegment()

Short description

Create a finite length line segment between two given endpoints. By providing vectors of end-points, several line segments can be created.

Parameters
Name	Type	Description
point1	CONST_OBJECT Point	First endpoint (2D) of the line segment. Can also be a vector of points to create several line segments.
point2	CONST_OBJECT Point	Second endpoint (2D) of the line segment. For vector input the length of the vector must match the vector containing the first endpoints

Return values
Name	Type	Description
lineSegment	OBJECT Shape	The created line segment, or vector of line segments for for vector input.

Sample

lineSegment = Shape.createLineSegment(point1, point2)

createPolyline()

Short description

Create a polyline shape (sequence of line segments connected to an open contour or closed polygon).

Parameters
Name	Type	Description
points	CONST_OBJECT Point	List of points (2D) to connect to a polyline
closed	BOOL	If true, the first and last points are connected to form a closed polygon. Otherwise it becomes an open contour.

Return values
Name	Type	Description
polyline	OBJECT Shape	The created polyline or polygon shape

Sample

polyline = Shape.createPolyline(points, true)

createRectangle()

Short description

Create a rectangle shape. Width and height must be non-negative. By providing vectors of centers, width, height and rotation, several rectangles can be created. All vectors must be of equal length.

Parameters
Name	Type	Description
center	CONST_OBJECT Point	Center point (2D) of the rectangle. Can also be a vector of center points to create several rectangles.
width	FLOAT	Rectangle width (size along the x axis before rotation). Can also be a vector of center points to create several rectangles.
height	FLOAT	Rectangle height (size along the y axis before rotation). Can also be a vector of heights to create several rectangles.
rotation	FLOAT	Optional rectangle rotation in radians, default is zero. A positive rotation rotates the x-axis towards the y-axis. Note that when used as region for an image, the image has a left-hand system with the y-axis pointing downwards, in which a positive rotation means a clockwise direction. Can also be a vector of rotations to create several rectangles.

Return values
Name	Type	Description
rectangle	OBJECT Shape	The created rectangle shape, or vector of rectangles for for vector input.

Sample

rectangle = Shape.createRectangle(center, width, height, rotation)

createSector()

Short description

Create a circular sector defining a region contained within two angles, an inner and an outer radius. Radii and deltaAngle must be non-negative, outerRadius must be larger than innerRadius. By providing vectors of centers, innerRadius, outerRadius, angle and deltaAngle several sectors can be created. All vectors must be of equal length.

See also

Shape.getSectorParameters

Parameters
Name	Type	Description
center	CONST_OBJECT Point	Center point of the circle from which the sector is defined. Can also be a vector of center points to create several sectors.
innerRadius	FLOAT	Inner radius of the sector. Can also be a vector of inner radii to create several sectors.
outerRadius	FLOAT	Outer radius of the sector. Can also be a vector of outer radii to create several sectors.
angle	FLOAT	Angle where the sector starts, in radians. Can also be a vector of angles to create several sectors.
deltaAngle	FLOAT	The angular length of the sector, in radians. Can also be a vector of delta angles to create several sectors.

Return values
Name	Type	Description
sector	OBJECT Shape	The created sector, or vector of sectors for for vector input.

Sample

sector = Shape.createSector(center, innerRadius, outerRadius, angle, deltaAngle)

cropLine()

Short description

Returns the part of a line within a rectangle as a new line segment. If the line does not intersect the rectangle, nil is returned. Several lines in a vector can be cropped at once, in which case all lines must be within the box for the call to succeed.

Parameters
Name	Type	Description
line	CONST_OBJECT Shape	The line shape to be cropped, or a vector of lines to be cropped.
rectangle	CONST_OBJECT Shape	The rectangle to keep the line within.

Return values
Name	Type	Description
line	OBJECT Shape	The part of the line within the rectangle as a line segment, or a vector of line segments. Nil is returned if any line is outside the box.

Sample

lineSegment = Shape.cropLine(line, rectangle)

getArcParameters()

Short description

Get the parameters defining the arc. Can only be called for arc shapes (returns nil otherwise). A vector of arc shapes can be provided, in which case vectors of parameters are returned.

Parameters
Name	Type	Description
arc	CONST_OBJECT Shape	Input arc shape or vector of arc shapes.

Return values
Name	Type	Description
center	OBJECT Point	Center point of the circle from which the arc is defined, or vector of center points for vector input.
radius	FLOAT	Radius of the arc, or vector of radii for vector input.
angleRad	FLOAT	Angle where the arc starts, in radians, or vector of angles for vector input.
deltaAngleRad	FLOAT	The angular length of the arc, in radians, or vector of angular lengths for vector input.

Sample

center, radius, angleRad, deltaAngleRad = Shape.getArcParameters(arc)

getArea()

Short description

Get the area of the region enclosed by a 2D Shape. A vector of shapes can be provided, in which case a vector of areas is returned.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape	Input shape or vector of shapes.

Return values
Name	Type	Description
area	FLOAT	Area of shape, or vector of areas for vector input.

Sample

area = Shape.getArea(shape)

getBoundingBox()

Short description

Get a rectangular axis-aligned bounding box of the shape (minimum box that contains the shape). The returned box is another Shape object. To get the actual bounds as float values, call getBounds.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape	Input shape or shapes

Return values
Name	Type	Description
boundingBox	OBJECT Shape	Axis-aligned bounding box as a rectangle shape, or vector for vector input.

Sample

boundingBox = Shape.getBoundingBox(shape)

getBoundingBoxOriented()

Short description

Gets a rectangular rotated bounding box of the given shape. This is the minimum area rectangle that still contains the shape. The return box is another Shape object.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape	Input shape or shapes.

Return values
Name	Type	Description
minimumAreaRectangle	OBJECT Shape	The oriented minimum area bounding box, or vector for vector input.

Sample

minimumAreaRectangle = Shape.getBoundingBoxOriented(shape)

getBounds()

Short description

Get the bounds of the shape as float values. Fails for invalid and unbounded shapes.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape	Input shape

Return values
Name	Type	Description
xMin	FLOAT	Minimum x coordinate
yMin	FLOAT	Minimum y coordinate
xMax	FLOAT	Maximum x coordinate
yMax	FLOAT	Maximum y coordinate

Sample

xMin, yMin, xMax, yMax = Shape.getBounds(shape)

getCenterOfGravity()

Short description

Get the center of gravity of the region enclosed within the shape for closed shapes. For open shapes, the center of gravity of the contour is returned. Returns nil for infinite or invalid shapes.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape	Input shape or vector of shapes.

Return values
Name	Type	Description
centerOfGravity	OBJECT Point	Center of gravity as a 2D Point, or vector of points for vector input.

Sample

point = Shape.getCenterOfGravity(shape)

getCircleParameters()

Short description

Get the parameters defining the circle. Can only be called for circle shapes (returns nil otherwise). A vector of circle shapes can be provided, in which case vectors of parameters are returned.

Parameters
Name	Type	Description
circle	CONST_OBJECT Shape	Input circle shape or vector of circle shapes.

Return values
Name	Type	Description
center	OBJECT Point	Center point of the circle, or vector of center points for vector input.
radius	FLOAT	Radius of the circle, or vector of radii for vector input.

Sample

center, radius = Shape.getCircleParameters(circle)

getClosestContourPoint()

Short description

Get the closest point on a shape contour to a given external point. Fails if the point is not a 2D point. If there are more than one shape provided the closest point on any shape countour is returned. If there are more than one point provided one point is returned for each input point.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape	Shape to process.
point	CONST_OBJECT Point	Point to process.

Return values
Name	Type	Description
closestPoint	OBJECT Point	Closest point on any of the shapes.
distance	FLOAT	The distance to the closest point.

Sample

closestPoint = Shape.getClosestContourPoint(shape, point)

getCompactness()

Short description

Gets a measure of how compact a shape is, as a number between 0.0 and 1.0. A circle has compactness 1.0. The measure is calculated as (4*pi*Area)/perimeter^2. Degenerate shapes has compactness zero.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape	Input shape or vector of shapes.

Return values
Name	Type	Description
compactness	FLOAT	Compactness of a shape, or vector for vector input.

Sample

compactness = Shape.getCompactness(shape)

getContourPoints()

Short description

Get the points defining the shape contour. Only supported for shapes consisting of a finite number of points (line segments, rectangles and polylines). To get a polygon approximation of a circle or ellipse, use toPolyline.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape	Shape to process

Return values
Name	Type	Description
points	OBJECT Point	List of points (2D) that approximates or represents the input shape.

Sample

points = Shape.getContourPoints(shape)

getConvexHull()

Short description

Gets the convex hull of a given shape. Currently fails if the shape is something other than a polyline. Convert general shapes to polylines using Shape.toPolyline.

See also

Shape.toPolyline

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape	Shape or shapes to process.

Return values
Name	Type	Description
hull	OBJECT Shape	Resulting convex hull as a polyline, or vector for vector input.

Sample

hull = Shape.getConvexHull(shape)

getConvexity()

Short description

Returns a measure of how convex a given shape is, as a number between 0.0 and 1.0. It is given as a quotient between the area of the shape and its convex hull. A convex object has convexity 1.0. All open shapes such as lines, arcs and open polylines return 0.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape	Input shape or vector of shapes.

Return values
Name	Type	Description
convexity	FLOAT	A measure of how convex the shape is, or vector of measurements for vector input.

Sample

convexity = Shape.getConvexity(shape)

getEllipseParameters()

Short description

Get the parameters defining the ellipse. Can only be called for ellipse shapes (returns nil otherwise). A vector of ellipse shapes can be provided, in which case vectors of parameters are returned.

Parameters
Name	Type	Description
ellipse	CONST_OBJECT Shape	Input ellipse shape or vector of ellipse shapes.

Return values
Name	Type	Description
center	OBJECT Point	Center point (2D), or vector of center points for vector input.
radiusX	FLOAT	Radius along the x axis (before rotation), or vector of radii for vector input.
radiusY	FLOAT	Radius along the y axis (before rotation), or vector of radii for vector input.
rotationRad	FLOAT	Ellipse rotation, in radians. Vector of rotations for vector input.

Sample

center, radiusX, radiusY, rotationRad = Shape.getEllipseParameters(ellipse)

getElongation()

Short description

Get the a measure of elongation of a shape. It is calculated as lengthAlongMajorAxis/lengthAlongMinorAxis and is therefore a number between 1.0 (e.g., a circle) and infinity (e.g., a line). For some shapes, i.e, Polyline, Arc and Sector, the elongation of the shape bounding box is returned.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape	Input shape or vector of shapes.

Return values
Name	Type	Description
elongation	FLOAT	Elongation, or vector of elongations for vector input.

Sample

elongation = Shape.getElongation(shape)

getIntersectionAngle()

Short description

Get angle of the intersection between two lines or line segments. If the line segments do not intersect the lines are extrapolated to calculate the intersection angle.

Parameters
Name	Type	Description
line1	CONST_OBJECT Shape	First shape. Must be a line or line segment.
line2	CONST_OBJECT Shape	Second shape. Must be a line or line segment.

Return values
Name	Type	Description
angle	FLOAT	Intersection angle, in radians.

Sample

angle = Shape.getIntersectionAngle(line1, line2)

getIntersectionPoints()

Short description

Get points on the intersection between two shape contours.

Parameters
Name	Type	Description
shape1	CONST_OBJECT Shape	First shape to intersect.
shape2	CONST_OBJECT Shape	Second shape to intersect.

Return values
Name	Type	Description
points	OBJECT Point	List of intersection points.

Sample

points = Shape.getIntersectionPoints(shape1, shape2)

getLineDistance()

Short description

Returns the minimum and maximum distance from all points on the shape to the reference line. Distances are measured orthogonal to the reference line. The query shape should have finite size.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape	The shape or shapes to check distance to.
referenceLine	CONST_OBJECT Shape	The reference line.

Return values
Name	Type	Description
minDist	FLOAT	The orthogonal distance from the line to the closest point on the shape, or nil if projection failed. Vector with distances for vector input.
maxDist	FLOAT	The orthogonal distance from the line to the point on the shape furthest away from the line, or nil if projection failed. Vector with distances for vector input.

Sample

minDist, maxDist = Shape.getLineDistance(shape, referenceLine)

getLineParameters()

Short description

Get the parameters defining the line or line segment. Can only be called for line or line segment shapes (returns nil otherwise). For line segments, the two endpoints are returned. For lines, the first point used to define the line is returned, the second point is one unit distance away from the first point along the line. A vector of line or line segment shapes can be provided, in which case two vectors of parameters are returned.

Parameters
Name	Type	Description
line	CONST_OBJECT Shape	Input line or line segment shape or vector of line or line segment shapes.

Return values
Name	Type	Description
point1	OBJECT Point	First line segment endpoint or one point on the line, or vector of points for vector input.
point2	OBJECT Point	Second line segment endpoint or another point on the line, or vector of points for vector input.

Sample

point1, point2 = Shape.getLineParameters(line)

getPerimeterLength()

Short description

Get the length of the perimeter of a shape.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape	Input shape or vector of shapes.

Return values
Name	Type	Description
perimeterLength	FLOAT	Perimeter length, or vector of lengths for vector input.

Sample

perimeterLength = Shape.getPerimeterLength(shape)

getPolylineParameters()

Short description

Get the points defining the polyline and a flag indicating if the polyline is closed.

Parameters
Name	Type	Description
polyline	CONST_OBJECT Shape	The polyline.

Return values
Name	Type	Description
points	OBJECT Point	Vertices for the polyline.
closed	BOOL	If true, the first and last points are connected to form a closed polygon. Otherwise it is an open contour.

Sample

points, closed = Shape.getPolylineParameters(polyline)

getRadius()

Short description

Get the radius of the shape. This function is deprecated. Use specific functions for getting the parameters of each Shape instead, for example Shape.getCircleParameters, or the bounding box functions.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape	Input shape

Return values
Name	Type	Description
radius	FLOAT	Radius of circumscribed circle

Sample

radius = Shape.getRadius(shape)

getRectangleParameters()

Short description

Get the parameters defining the rectangle. Can only be called for rectangle shapes (returns nil otherwise). A vector of rectangle shapes can be provided, in which case three vectors of parameters are returned.

Parameters
Name	Type	Description
rectangle	CONST_OBJECT Shape	Input rectangle shape or vector of rectangle shapes.

Return values
Name	Type	Description
center	CONST_OBJECT Point	Center point (2D) of the rectangle, or vector of center points for vector input.
width	FLOAT	Rectangle width (size along the x axis before rotation), or vector of widths for vector input.
height	FLOAT	Rectangle height (size along the y axis before rotation), or vector of heights for vector input.
rotation	FLOAT	Rectangle rotation in radians. Counter-clockwise rotation in an x/y coordinate system. Vector of rotations for vector input.

Sample

center, width, height, rotationRad = Shape.getRectangleParameters(rectangle)

getSectorParameters()

Short description

Get the parameters defining the sector. Can only be called for sector shapes (returns nil otherwise). A vector of sector shapes can be provided, in which case vectors of parameters are returned.

Parameters
Name	Type	Description
sector	CONST_OBJECT Shape	Input sector shape or vector of sector shapes.

Return values
Name	Type	Description
center	OBJECT Point	Center point of the circle from which the sector is defined, or vector of center points for vector input.
innerRadius	FLOAT	Inner radius of the sector, or vector of inner radii for vector input.
outerRadius	FLOAT	Outer radius of the sector, or vector of outer radii for vector input.
angleRad	FLOAT	Angle where the sector starts, in radians, or vector of angles for vector input.
deltaAngleRad	FLOAT	The angular length of the sector, in radians. Vector of angular lengths for vector input.

Sample

center, innerRadius, outerRadius, angleRad, deltaAngleRad = Shape.getSectorParameters(sector)

getType()

Short description

Return the geometric type the Shape represents.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape	The shape or shapes to check.

Return values
Name	Type	Description
shapeType	ENUM ShapeType	The shape type or vector with shape types.

Sample

shapeType = Shape.getType(shape)

isClosed()

Short description

Check if this is a closed shape. A contour is closed if it has no endpoints and encloses an area. For example, a circle is closed while a line segment is not.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape	The shape or shapes to check

Return values
Name	Type	Description
isClosed	BOOL	True if the shape is closed, otherwise false

Sample

isClosed = Shape.isClosed(shape)

rotate()

Short description

Rotate the shape. The rotation center is optional. If not provided, the nominal center of the shape is used. For most shapes, this is the same point as the center of gravity. For arcs and sectors, the nominal center is the center of the base circle. Note on rotation direction: When a shape is used for defining a region in an image, it is interpreted in the left handed coordinate system of the image. In a left-handed system, a positive rotation is in the clockwise direction.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape	Input shape or shapes.
rotationAngle	FLOAT	The rotation angle in radians
rotationCenter	CONST_OBJECT Point	The rotation center. The nominal center of the shape is used if unspecified.

Return values
Name	Type	Description
outputShape	OBJECT Shape	The rotated shape or shapes, or nil if the input shape is invalid.

Sample

outputShape = Shape.rotate(shape, rotationAngle, rotationCenter)

toImage()

Short description

Convert the shape into an image, setting pixels within the shape contour to a specific value. The value is in world coordinates and is cropped to the representable range. Pixels outside are set to pixel value zero. Only closed shapes are supported. If several shapes are given, they are all drawn in the same image. Invalid shapes in a list of shapes are ignored.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape	Input shape or vector of shapes.
referenceImage	CONST_OBJECT Image	Reference image, used to define pixel-world mapping.
worldValue	FLOAT	World value to use within the region. Default is 255.

Return values
Name	Type	Description
outputImage	OBJECT Image	Resulting image displaying the shape or nil if not supported.

Sample

outputImage = Shape.toImage(shape,refImage,worldValue)

toLine()

Short description

Convert a line segment or a vector of line segments to infinite lines. Only supports line segment input.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape	Line segment or vector of line segments to convert.

Return values
Name	Type	Description
line	OBJECT Shape	Line or vector of lines created by extending the line segment end points to infinity.

Sample

line = Shape.toLine(lineSegment)

toPixelRegion()

Short description

Rasterize a Shape object into a PixelRegion object, using a reference image to define the pixel-world mapping. A vector of shape objects generates a vector of PixelRegion objects.

Keywords

draw, render, rasterize

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape	Input shape or shapes.
referenceImage	CONST_OBJECT Image	Reference image, used to define pixel-world mapping.
fill	BOOL	Set to true to generate a filled region, false to generate a border region. Non-closed shapes will always generate a border only. Default: true.

Return values
Name	Type	Description
pixelRegion	OBJECT Image.PixelRegion	Pixel region representation of the shape, or a vector of pixel region representations of the shapes.

Sample

pixelRegion = Shape.toPixelRegion(shape, referenceImage)

toPolyline()

Short description

Convert this shape to a polyline shape, approximating the true shape if needed (if the true shape is a circle, ellipse or arc). For a shape that is already a polyline, this function can be used to approximate it with a less detailed polyline.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape	Shape to convert, or vector of shapes.
epsilon	FLOAT	Maximum approximation error in the polyline approximation.
maxPoints	INT	Maximum number of points to use in the approximation (default is 1000). This is a stronger requirement than the epsilon and puts a limit on the function memory usage.

Return values
Name	Type	Description
polylineShape	OBJECT Shape	The shape represented as a polyline, or vector of polylines.

Sample

polylineShape = Shape.toPolyline(shape, epsilon)

toShape3D()

Short description

Convert a 2D Shape into the corresponding 3D shape. An optional rigid Transform object may be provided. Without transform, the 3D shape is created in the z=0 plane. The transform is applied after creation, allowing 3D Shapes in other planes. Nil is returned if the input contains invalid shapes or shapes without a corresponding 3D shape.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape	Input shape or vector of shapes.
transform	CONST_OBJECT Transform	Optional transform from the z=0 plane to the desired plane. Must be rigid or less general.

Return values
Name	Type	Description
outputShape	OBJECT Shape3D	The corresponding Shape3D or nil if not supported, or vector of 3D shapes.

Sample

outputShape = Shape.toShape3D(shape, transform)

toString()

Short description

Get a human-readable string describing the shape.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape	Input shape

Return values
Name	Type	Description
str	STRING	String description of the shape

Sample

print(Shape.toString(shape))

transform()

Short description

Transform a shape or a vector of shapes. Fails if the transform is not a 2D transform or if the transform would change the underlying shape type.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape	Input shape or shapes.
transform	CONST_OBJECT Transform	Transform to apply.

Return values
Name	Type	Description
outputShape	OBJECT Shape	Transformed shape or shapes, or nil on error.

Sample

outputShape = Shape.transform(shape, transform)

translate()

Short description

Translate the shape, i.e., shift it along the x,y-axes. Note on translation direction: When a shape is used for defining a region in an image, it is interpreted in the left handed coordinate system of the image in which the y-axis is pointing downwards. A positive translation therefore shifts the shape downwards when overlaid on top of the image.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape	Input shape or shapes
translationX	FLOAT	The translation along the X-axis
translationY	FLOAT	The translation along the Y-axis

Return values
Name	Type	Description
outputShape	OBJECT Shape	The translated shape or shapes, or nil if the input shape is invalid

Sample

outputShape = Shape.translate(shape, translationX, translationY)

Shape.Composite

Short description

Composite of several individual shapes. The composite contains a set of positive shapes and an optional set of negative shapes, and the final shape is the union of all positive shapes, with the union of all negative shapes removed. The order of the shapes has no significance.

Keywords

draw, rasterize, render

Overview

addShape(), clone(), contains(), create(), getPositiveBoundingBox(), getShape(), getShapeCount(), toImage(), toPixelRegion(), toPolygons(), toString(), transform()

Functions

addShape()

Short description

Add a shape to the composite

Parameters
Name	Type	Description
composite	OBJECT Shape.Composite	The composite to modify
shape	CONST_OBJECT Shape	The shape to add
isPositive	BOOL	True means positive shape, false means negative shape (default is positive)

Sample

Shape.Composite.addShape(composite, shape, isPositive)

clone()

Short description

Create an independent deep copy of the composite

Parameters
Name	Type	Description
inputComposite	CONST_OBJECT Shape.Composite	Input composite

Return values
Name	Type	Description
outputComposite	OBJECT Shape.Composite	Deep copy of the input composite

Sample

sc2 = Shape.Composite.clone(sc)

contains()

Short description

Check if the given point is within this composite (within any of the positive shapes but not within any of the negative ones). False is returned if any invalid shape is in the composite.

Parameters
Name	Type	Description
composite	CONST_OBJECT Shape.Composite	Input composite
point	CONST_OBJECT Point	Point to check

Return values
Name	Type	Description
result	BOOL	True if the point is within the region, otherwise false

Sample

b = Shape.Composite.contains(composite, point)

create()

Short description

Create an empty shape composite

Return values
Name	Type	Description
composite	OBJECT Shape.Composite	The created shape composite.

Sample

sc = Shape.Composite.create()

getPositiveBoundingBox()

Short description

Get a bounding box of all positive shapes. This box is guaranteed to contain the entire region but might not be the tightest possible box if negative regions are used.

Parameters
Name	Type	Description
composite	CONST_OBJECT Shape.Composite	The composite to use

Return values
Name	Type	Description
box	OBJECT Shape	Rectangle shape representing the bounding box

Sample

box = Shape.Composite.getPositiveBoundingBox(composite)

getShape()

Short description

Get one of the shapes and its associated isNegative flag

Parameters
Name	Type	Description
composite	CONST_OBJECT Shape.Composite	Input shape composite
index	INT	Index of the shape to return (0-based)

Return values
Name	Type	Description
shape	OBJECT Shape	The requested shape
isPositive	BOOL	True if the shape is positive, otherwise false

Sample

shape, isPositive = Shape.Composite.getShape(composite, index)

getShapeCount()

Short description

Get the number of shapes contained in this composite

Parameters
Name	Type	Description
composite	CONST_OBJECT Shape.Composite	Input shape composite

Return values
Name	Type	Description
count	INT	Number of shapes in the composite (positive and negative)

Sample

n = Shape.Composite.getShapeCount(composite)

toImage()

Short description

Convert the composite shape into an image, setting pixels within the shape contour to a specific value. The value is in world coordinates and is cropped to the representable range. Pixels outside are set to pixel value zero.

Parameters
Name	Type	Description
composite	CONST_OBJECT Shape.Composite	Input composite
referenceImage	CONST_OBJECT Image	Image used to define world-pixel coordinate conversion and target resolution
worldValue	FLOAT	World value to use within the region. Default is 255.

Return values
Name	Type	Description
outputImage	OBJECT Image	The converted image

Sample

image = Shape.Composite.toImage(shapeComposite, referenceImage, worldValue)

toPixelRegion()

Short description

Convert a shape composite to a pixel region. This is useful for showing the composite in a viewer, or to use the composite region as input to image processing methods.

Parameters
Name	Type	Description
composite	CONST_OBJECT Shape.Composite	Composite shape region to convert.
referenceImage	CONST_OBJECT Image	Reference image, defines the image world coordinate system.

Return values
Name	Type	Description
outputRegion	OBJECT Image.PixelRegion	Input composite converted to a PixelRegion.

Sample

pixelRegion = Shape.Composite.toPixelRegion(composite, referenceImage)

toPolygons()

Short description

Convert the shape composite to a composite consisting only of polygons. All circle and ellipses in the input are approximated by polygons with a given maximum error.

Parameters
Name	Type	Description
inputComposite	CONST_OBJECT Shape.Composite	Input composite
epsilon	FLOAT	Maximum approximation error. Controls the number of points used in the polygon approximation of ellipses and circles
maxPoints	INT	Maximum number of points to use in the approximation if each polygon (default is 1000). This is a stronger requirement than the epsilon and puts a limit on the function memory usage.

Return values
Name	Type	Description
outputComposite	OBJECT Shape.Composite	Polygon composite shape.

Sample

outputComposite = Shape.Composite.toPolygons(inputComposite, epsilon)

toString()

Short description

Gets a user-friendly string description of the composite shape.

Parameters
Name	Type	Description
composite	CONST_OBJECT [API:DataFormat:]	The composite shape to describe.

Return values
Name	Type	Description
str	STRING	User-friendly description of the composite shape .

Sample

str = Shape.Composite.toString(composite)

transform()

Short description

Transform the composite according to a general 2D transformation. Requires that all individual shapes support the transformation. For example, if one of the shapes is a circle and the transformation is an affine transformation, the operation will fail, since circles are no longer circles after an affine transformation. For transforming any kind of composite, consider converting the composite to a polygon representation using toPolygons first.

Parameters
Name	Type	Description
composite	CONST_OBJECT Shape.Composite	Input shape composite
transform	CONST_OBJECT Transform	The transform to use (must be a 2D transform)

Return values
Name	Type	Description
newComposite	OBJECT Shape.Composite	The transformed shape composite

Sample

newComposite = Shape.Composite.transform(composite, transform)

Shape3D

Short description

A 3D geometric primitive, e.g., Line, LineSegment, Polyline, Plane, Rectangle, Circle, Box, Sphere, Cylinder, Cone, etc. The pose (position and orientation) of most shapes is controlled by a 3D Transform. Such shapes have a defined default pose, often centered around the origin, from which the pose transform is used to move and rotate the shape into the desired pose in 3D space. When creating a shape, the pose transform is not allowed to change the size of the shape (the size is set by specific parameters), that is, the pose transform must be of rigid, rotation or translation type. Shapes can be transformed using more general transformations, however the type of transformations allowed is specific to each shape and limited to make sure the shape stays within its class. For example, a non-uniform scaling will turn a circle into an ellipse and is thus not allowed. The Shape3D object is represented in mathematical analytical form. Operations such as finding intersection points, distances and transforming the geometric primitive are for this reason efficiently computed.

Overview

clone(), contains(), countInside(), createBox(), createCircle(), createCone(), createCylinder(), createEllipse(), createEllipticCylinder(), createLine(), createLineSegment(), createPlane(), createPlaneFromPoints(), createPolygon(), createPolyline(), createRectangle(), createSphere(), cropLine(), fitLine(), fitPlane(), getArea(), getBoundingBox(), getBounds(), getBoxParameters(), getCenterOfGravity(), getCircleParameters(), getClosestSurfacePoint(), getConeApex(), getConeParameters(), getCylinderParameters(), getEllipseParameters(), getEllipticCylinderParameters(), getIntersectionAngle(), getIntersectionLine(), getIntersectionPoints(), getLineParameters(), getLineSegmentParameters(), getPlaneDistance(), getPlaneParameters(), getPlanePoints(), getPolygonParameters(), getPolylineParameters(), getRectangleParameters(), getSphereParameters(), getType(), getVolume(), isClosed(), isZeroVolume(), projectZ(), rotateX(), rotateY(), rotateZ(), toLine(), toPixelRegion(), toPlane(), toPolygon(), toString(), transform(), translate()

Functions

clone()

Short description

Create an independent copy of the shape. If the input is a vector of shapes, the output is a vector of shapes.

Parameters
Name	Type	Description
inputShape	CONST_OBJECT Shape3D	The shape to clone.

Return values
Name	Type	Description
outputShape	OBJECT Shape3D	The new copy.

Sample

outputShape = Shape3D.clone(inputShape)

contains()

Short description

Returns true if the supplied 3D point is within the shape. Returns false for all shapes with zero volume. If more than one shape is provided true is returned if the point is inside any of the shapes. If more than one point is provided a vector is returned with one value for each input point.

Parameters
Name	Type	Description
shape3d	CONST_OBJECT Shape3D	3D shape input.
point	CONST_OBJECT Point	The 3D point to probe.

Return values
Name	Type	Description
isInside	BOOL	True if the point is inside the shape.

Sample

isInside = Shape3D.contains(shape3d, point)

countInside()

Short description

Counts the number of points that fall within the shape.

Parameters
Name	Type	Description
shape3d	CONST_OBJECT Shape3D	3D shape input.
points	CONST_OBJECT Point	The 3D points to probe.

Return values
Name	Type	Description
count	INT	The number of points within the shape.

Sample

count = Shape3D.countInside(shape3d, points)

createBox()

Short description

Create a box in 3D space. Unless transformed, the box is centered on the origin.

Parameters
Name	Type	Description
sizeX	FLOAT	Size of the box in the x-direction before transformation.
sizeY	FLOAT	Size of the box in the y-direction before transformation.
sizeZ	FLOAT	Size of the box in the z-direction before transformation.
poseTransform	CONST_OBJECT Transform	Transform defining the box position and orientation in 3D space. Must be of type identity, translation or rigid. Optional, default is an identity transform.

Return values
Name	Type	Description
box	OBJECT Shape3D	The created box.

Sample

box = Shape3D.createBox(sizeX, sizeY, sizeZ, poseTransform)

createCircle()

Short description

Create a 2D circle embedded in 3D space. Unless transformed, the circle is created in the xy-plane, centered on the origin.

Parameters
Name	Type	Description
radius	FLOAT	Radius of the circle.
poseTransform	CONST_OBJECT Transform	Transform defining the circle position and orientation in 3D space. Must be of type identity, translation or rigid. Optional, default is an identity transform.

Return values
Name	Type	Description
circle	OBJECT Shape3D	The created 3D circle.

Sample

circle = Shape3D.createCircle(radius, poseTransform)

createCone()

Short description

Create a cone in 3D space. Unless transformed, the z-axis is the symmetry axis of the cone, the base circle is centered on the origin and the apex is at the point (0, 0, heightZ).

Parameters
Name	Type	Description
radius	FLOAT	Largest radius of the cone.
heightZ	FLOAT	Height of the cone in the z-direction before transformation.
poseTransform	CONST_OBJECT Transform	Transform defining the cone position and orientation in 3D space. Must be of type identity, translation or rigid. Optional, default is an identity transform.

Return values
Name	Type	Description
cone	OBJECT Shape3D	The created cone.

Sample

cone = Shape3D.createCone(radius, heightZ, poseTransform)

createCylinder()

Short description

Create a cylinder in 3D space. Unless transformed, the cylinder is centered on the origin with the z-axis as symmetry line.

Parameters
Name	Type	Description
radius	FLOAT	Radius in the xy-plane before transformation.
heightZ	FLOAT	Height of the cylinder in the z-direction before transformation.
poseTransform	CONST_OBJECT Transform	Transform defining the cylinder position and orientation in 3D space. Must be of type identity, translation or rigid. Optional, default is an identity transform.

Return values
Name	Type	Description
cylinder	OBJECT Shape3D	The created cylinder.

Sample

cylinder = Shape3D.createCylinder(radius, heightZ, poseTransform)

createEllipse()

Short description

Create a 2D ellipse embedded in 3D space. Unless transformed, the ellipse is created in the xy-plane, centered on the origin.

Parameters
Name	Type	Description
radiusX	FLOAT	Radius of the ellipse in the x-direction before transformation.
radiusY	FLOAT	Radius of the ellipse in the y-direction before transformation.
poseTransform	CONST_OBJECT Transform	Transform defining the ellipse position and orientation in 3D space. Must be of type identity, translation or rigid. Optional, default is an identity transform.

Return values
Name	Type	Description
ellipse	OBJECT Shape3D	The created 3D ellipse.

Sample

ellipse = Shape3D.createEllipse(radiusX, radiusY, poseTransform)

createEllipticCylinder()

Short description

Create an elliptic cylinder in 3D space. Unless transformed, the elliptic cylinder is centered on the origin centered on the z-axis.

Parameters
Name	Type	Description
radiusX	FLOAT	Radius in the x-direction before transformation.
radiusY	FLOAT	Radius in the y-direction before transformation.
heightZ	FLOAT	Height of the elliptic cylinder in the z-direction before transformation.
poseTransform	CONST_OBJECT Transform	Transform defining the elliptic cylinder position and orientation in 3D space. Must be of type identity, translation or rigid. Optional, default is an identity transform.

Return values
Name	Type	Description
ellipticCylinder	OBJECT Shape3D	The created elliptic cylinder.

Sample

ellipticCylinder = Shape3D.createEllipticCylinder(radiusX, radiusY, heightZ, poseTransform)

createLine()

Short description

Create a line in 3D, passing through the two given 3D points.

Parameters
Name	Type	Description
point1	CONST_OBJECT Point	First 3D point on the line.
point2	CONST_OBJECT Point	Second 3D point on the line.

Return values
Name	Type	Description
line	OBJECT Shape3D	The created 3D line, or nil if the two point coincide.

Sample

line = Shape3D.createLine(point1, point2)

createLineSegment()

Short description

Create a line segment in 3D between the two given 3D points.

Parameters
Name	Type	Description
point1	CONST_OBJECT Point	First 3D endpoint of the line segment.
point2	CONST_OBJECT Point	Second 3D endpoint of the line segment.

Return values
Name	Type	Description
lineSegment	OBJECT Shape3D	The created 3D line segment, or nil if the two point coincide.

Sample

lineSegment = Shape3D.createLineSegment(point1, point2)

createPlane()

Short description

Create a plane in 3D. A plane is defined by its normal vector (vector perpendicular to the plane) and a distance from the world origin (Hesse normal form). For example, an XY-aligned plane at Z = 5 is constructed using Shape3D.createPlane(0, 0, 1, 5). The distance is signed and measured from the origin along the normal. A plane where the normal points from the plane towards the origin has a negative distance.

Parameters
Name	Type	Description
nx	FLOAT	X component of plane normal vector.
ny	FLOAT	Y component of plane normal vector.
nz	FLOAT	Z component of plane normal vector.
distance	FLOAT	Distance from the origin to the plane along the plane normal.

Return values
Name	Type	Description
plane	OBJECT Shape3D	The created plane, or nil if the normal vector was a zero vector.

Sample

plane = Shape3D.createPlane(nx, ny, nz, distance)

createPlaneFromPoints()

Short description

Create a plane in 3D containing the three given 3D points. The three points must span a plane, i.e., they must not be distributed along a line.

Parameters
Name	Type	Description
point1	CONST_OBJECT Point	First 3D point.
point2	CONST_OBJECT Point	Second 3D point.
point3	CONST_OBJECT Point	Third 3D point.

Return values
Name	Type	Description
plane	OBJECT Shape3D	The created plane, or nil if the points are in a degenerate configuration.

Sample

plane = Shape3D.createPlaneFromPoints(point1, point2, point3)

createPolygon()

Short description

Create a 2D closed polygon embedded in 3D space. If the points are not in a plane, the points are projected onto the best fitting plane. At least three points are required.

Parameters
Name	Type	Description
points	CONST_OBJECT Point	Corner points for the polygon.

Return values
Name	Type	Description
polygon	OBJECT Shape3D	The created 2D polygon in 3D.

Sample

polygon = Shape3D.createPolygon(points)

createPolyline()

Short description

Create a full 3D polyline. Corners can be placed freely in 3D, however, a closed surface for a general 3D polyline would be ambiguous and thus this shape can not be closed. Use the 3D polygon for closed shapes.

Parameters
Name	Type	Description
points	CONST_OBJECT Point	Corner points for the polyline.

Return values
Name	Type	Description
polyline	OBJECT Shape3D	The created polyline.

Sample

polyline = Shape3D.createPolyline(points)

createRectangle()

Short description

Create a 2D rectangle embedded in 3D space. Unless transformed, the rectangle is created in the xy-plane, centered on the origin.

Parameters
Name	Type	Description
sizeX	FLOAT	Size of the rectangle in the x-direction before transformation (width).
sizeY	FLOAT	Size of the rectangle in the y-direction before transformation (height).
poseTransform	CONST_OBJECT Transform	Transform defining the rectangle position and orientation in 3D space. Must be of type identity, translation or rigid. Optional, default is an identity transform.

Return values
Name	Type	Description
rectangle	OBJECT Shape3D	The created 3D rectangle.

Sample

rectangle = Shape3D.createRectangle(sizeX, sizeY, poseTransform)

createSphere()

Short description

Create a sphere in 3D space. Unless transformed, the sphere is centered on the origin.

Parameters
Name	Type	Description
radius	FLOAT	Radius of the sphere.
poseTransform	CONST_OBJECT Transform	Transform defining the sphere position and orientation in 3D space. Must be of type identity, translation or rigid. The sphere itself is invariant to rotations however the orientation of the local coordinate system is affected. Optional, default is an identity transform.

Return values
Name	Type	Description
sphere	OBJECT Shape3D	The created sphere.

Sample

sphere = Shape3D.createSphere(radius, poseTransform)

cropLine()

Short description

Returns the part of a line within a box as a new line segment. If the line does not intersect the box, nil is returned.

Parameters
Name	Type	Description
line	CONST_OBJECT Shape3D	The line shape to be cropped.
box	CONST_OBJECT Shape3D	The box to crop the line with.

Return values
Name	Type	Description
line	OBJECT Shape3D	The part of the line within the box as a line segment.

Sample

lineSegment = Shape3D.cropLine(line, box)

fitLine()

Short description

Fit a 3D line to a set of 3D-points. Different fitting and outlier handling modes are available. Fitting mode may be any of: LEASTSQUARES - Ordinary least squares, fast but not robust against outliers. RANSAC - Outlier rejection by random sampling and consensus. The trade-off between speed and robustness can be adjusted using an iteration parameter. TRIMMED - Two stages of least squares fitting with outlier rejection between the stages. Performance is in general in between RANSAC and least squares with respect to robustness and speed. For RANSAC and trimmed modes, outliers are specified with a margin parameter in one of the following ways: ABSOLUTE - Absolute outlier margin, points with a distance larger than the specified distance from the line are treated as outliers. RANK - Defines the fraction of points to treat as inlier points. For example, a rank margin of 0.7 means that the best 70% of all points are included and the rest are ignored as outliers. If there are additional points close to the margin, those will also be included such that the final inlier fraction may be higher.

Parameters
Name	Type	Description
points	CONST_OBJECT Point	Input points.
mode	ENUM Shape3D.ShapePointFitMode	Fitting mode. Default is LEASTSQUARES.
marginType	ENUM Shape.OutlierMarginType	Outlier margin type (ABSOLUTE or RANK). Only used in fitting modes: RANSAC and TRIMMED. Default is ABSOLUTE.
margin	FLOAT	Inlier margin, the interpretation depends on the margin type. Only used in iterative fitting modes: RANSAC and TRIMMED. Default is 2.0 for ABSOLUTE and 0.5 for RANK.
iterations	INT	Number of iterations. Only used in iterative fitting mode: RANSAC.

Return values
Name	Type	Description
line	OBJECT Shape3D	The 3D line with best fit.
quality	FLOAT	Vector with fitting quality measurements [meanError, inlierRate], where meanError is the average fitting error of inlier points in world coordinates and inlierRate is the rate of input points that were accepted as belonging to the line.

Sample

line3d, quality = Shape3D.fitLine(points, mode, margin, iterations)

fitPlane()

Short description

Fit a plane shape to a set of 3D-points. Different fitting and outlier handling modes are available. Fitting mode may be any of: LEASTSQUARES - Ordinary least squares, fast but not robust against outliers. RANSAC - Outlier rejection by random sampling and consensus. The trade-off between speed and robustness can be adjusted using an iteration parameter. TRIMMED - Two stages of least squares fitting with outlier rejection between the stages. Performance is in general in between RANSAC and least squares with respect to robustness and speed. For RANSAC and trimmed modes, outliers are specified with a margin parameter in one of the following ways: ABSOLUTE - Absolute outlier margin, points with a distance larger than the specified distance from the plane are treated as outliers. RANK - Defines the fraction of points to treat as inlier points. For example, a rank margin of 0.7 means that the best 70% of all points are included and the rest are ignored as outliers. If there are additional points close to the margin, those will also be included such that the final inlier fraction may be higher.

Parameters
Name	Type	Description
points	CONST_OBJECT Point	Input points.
mode	ENUM Shape3D.ShapePointFitMode	Fitting mode. Default is LEASTSQUARES.
marginType	ENUM Shape.OutlierMarginType	Outlier margin type (ABSOLUTE or RANK). Only used in fitting modes: RANSAC and TRIMMED. Default is ABSOLUTE.
margin	FLOAT	Inlier margin, the interpretation depends on the margin type. Only used in fitting modes: RANSAC and TRIMMED. Default is 2.0 for ABSOLUTE and 0.5 for RANK.
iterations	INT	Number of iterations. Only used in iterative fitting mode: RANSAC. Default is 20.

Return values
Name	Type	Description
plane	OBJECT Shape3D	Plane with best fit.
quality	FLOAT	Vector with fitting quality measurements [meanError, inlierRate], where meanError is the average fitting error of inlier points in world coordinates and inlierRate is the rate of input points that were accepted as belonging to the plane.

Sample

plane, quality = Shape3D.fitPlane(points, mode, margin, iterations)

getArea()

Short description

Returns the total surface area of the shape. For flat shapes, e.g., a rectangle, circle or ellipse in 3D space, only one side is counted.

Parameters
Name	Type	Description
shape3d	CONST_OBJECT Shape3D	3D shape input.

Return values
Name	Type	Description
area	FLOAT	The surface area of the shape.

Sample

area = Shape3D.getArea(shape3d)

getBoundingBox()

Short description

Returns the smallest axis aligned box that encloses the shape.

Parameters
Name	Type	Description
shape3d	CONST_OBJECT Shape3D	3D shape input.

Return values
Name	Type	Description
boundingBox	OBJECT Shape3D	The axis aligned bounding box of the shape.

Sample

boundingBox = Shape3D.getBoundingBox(shape3d)

getBounds()

Short description

Get the bounds of the shape as individual values.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape3D	Input shape

Return values
Name	Type	Description
xMin	FLOAT	Minimum x coordinate.
yMin	FLOAT	Minimum y coordinate.
zMin	FLOAT	Minimum z coordinate.
xMax	FLOAT	Maximum x coordinate.
yMax	FLOAT	Maximum y coordinate.
zMax	FLOAT	Maximum z coordinate.

Sample

xMin, yMin, zMin, xMax, yMax, zMax = Shape3D.getBounds(shape)

getBoxParameters()

Short description

Get the size and pose of the 3D box.

Parameters
Name	Type	Description
box	CONST_OBJECT Shape3D	The created box.

Return values
Name	Type	Description
sizeX	FLOAT	Size of the box in the x-direction before transformation.
sizeY	FLOAT	Size of the box in the y-direction before transformation.
sizeZ	FLOAT	Size of the box in the z-direction before transformation.
poseTransform	OBJECT Transform	Transform defining the box position and orientation in 3D space. Is of type identity, translation or rigid.

Sample

sizeX, sizeY, sizeZ, poseTransform = Shape3D.getBoxParameters(box)

getCenterOfGravity()

Short description

Returns the center of gravity of the shape. Returns nil for invalid shapes and for shapes with infinite size.

Parameters
Name	Type	Description
shape3d	CONST_OBJECT Shape3D	3D shape input.

Return values
Name	Type	Description
center	OBJECT Point	The center of gravity of the shape.

Sample

center = Shape3D.getCenterOfGravity(shape3d)

getCircleParameters()

Short description

Get the radius and pose of the 3D circle.

Parameters
Name	Type	Description
circle	OBJECT Shape3D	The 3D circle.

Return values
Name	Type	Description
radius	FLOAT	Radius of the circle.
poseTransform	CONST_OBJECT Transform	Transform defining the circle position and orientation in 3D space. Is of type identity, translation or rigid.

Sample

radius, poseTransform = Shape3D.getCircleParameters(circle)

getClosestSurfacePoint()

Short description

Returns the point on the shape surface (or edge) closest to the probe point. If there are more than one shape provided the closest point on any shape surface is returned. If there are more than one point provided one point is returned for each input point.

Parameters
Name	Type	Description
shape3d	CONST_OBJECT Shape3D	3D shape input.
point	CONST_OBJECT Point	The 3D point to probe.

Return values
Name	Type	Description
surfacePoint	OBJECT Point	The point on the surface closest to the probe point.
distance	FLOAT	The distance to the closest point.

Sample

surfacePoint = Shape3D.getClosestSurfacePoint(shape3d, point)

getConeApex()

Short description

Returns the position of the tip of the cone. Together with getCenterOfGravity, two points defining the direction of the cone can be found.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape3D	The cone.

Return values
Name	Type	Description
apex	OBJECT Point	The apex of the cone, or nil if any other shape is given.

Sample

apex = Shape3D.getConeApex(shape)

getConeParameters()

Short description

Get the radius, height and pose of a cone.

Parameters
Name	Type	Description
cone	OBJECT Shape3D	The cone.

Return values
Name	Type	Description
radius	FLOAT	The largest radius of the cone.
heightZ	FLOAT	Height of the cone from the base circle to the apex.
poseTransform	CONST_OBJECT Transform	Transform defining the cone position and orientation in 3D space. Is of type identity, translation or rigid.

Sample

radius, heightZ, poseTransform = Shape3D.getConeParameters(cone)

getCylinderParameters()

Short description

Get the radius, height and pose of a cylinder.

Parameters
Name	Type	Description
cylinder	OBJECT Shape3D	The created cylinder.

Return values
Name	Type	Description
radius	FLOAT	Radius in the xy-plane before transformation.
heightZ	FLOAT	Height of the cylinder in the z-direction before transformation.
poseTransform	CONST_OBJECT Transform	Transform defining the cylinder position and orientation in 3D space. Is of type identity, translation or rigid.

Sample

radius, heightZ, poseTransform = Shape3D.getCylinderParameters(cylinder)

getEllipseParameters()

Short description

Get the radii and pose transform of the 3D ellipse.

Parameters
Name	Type	Description
ellipse	OBJECT Shape3D	The 3D ellipse.

Return values
Name	Type	Description
radiusX	FLOAT	Radius of the ellipse in the x-direction before transformation.
radiusY	FLOAT	Radius of the ellipse in the y-direction before transformation.
poseTransform	CONST_OBJECT Transform	Transform defining the ellipse position and orientation in 3D space. Is of type identity, translation or rigid.

Sample

radiusX, radiusY, poseTransform = Shape3D.getEllipseParameters(ellipse)

getEllipticCylinderParameters()

Short description

Get the radii, height and pose of an elliptic cylinder.

Parameters
Name	Type	Description
ellipticCylinder	OBJECT Shape3D	The elliptic cylinder.

Return values
Name	Type	Description
radiusX	FLOAT	Radius in the x-direction before transformation.
radiusY	FLOAT	Radius in the y-direction before transformation.
heightZ	FLOAT	Height of the elliptic cylinder in the z-direction before transformation.
poseTransform	CONST_OBJECT Transform	Transform defining the elliptic cylinder position and orientation in 3D space. Is of type identity, translation or rigid.

Sample

radiusX, radiusY, heightZ, poseTransform = Shape3D.getEllipticCylinderParameters(ellipticCylinder)

getIntersectionAngle()

Short description

Get the sharpest angle between two flat Shape3D shapes (circle, rectangle, ellipse in 3D space, etc.), 3D lines, 3D line segments or combination thereof. The shapes do not need to intersect. The angle is in the range 0 to pi/2 where zero indicates parallel planes or lines. Shapes lying in orthogonal planes result in the angle pi/2. Nil is returned if either argument is not a flat shape or a line.

Parameters
Name	Type	Description
shape1	CONST_OBJECT Shape3D	Shape 1, a flat shape, line or line segment.
shape2	CONST_OBJECT Shape3D	Shape 2, a flat shape, line or line segment.

Return values
Name	Type	Description
angle	FLOAT	Sharpest angle between shapes, or Nil if shapes are not flat.

Sample

angle = Shape3D.getIntersectionAngle(shape1, shape2)

getIntersectionLine()

Short description

Returns the intersection line of two planes.

Parameters
Name	Type	Description
shape1	CONST_OBJECT Shape3D	First plane.
shape2	CONST_OBJECT Shape3D	Second plane.

Return values
Name	Type	Description
intersections	OBJECT Shape3D	Intersection line. If there is no intersection, an empty list is returned. If the shape combination is not supported, nil is returned.

Sample

intersections = Shape3D.getIntersectionLine(shape1, shape2)

getIntersectionPoints()

Short description

Returns the intersection points of two shapes. One of the shapes must be a line or a line segment.

Parameters
Name	Type	Description
shape1	CONST_OBJECT Shape3D	First shape.
shape2	CONST_OBJECT Shape3D	Second shape.

Return values
Name	Type	Description
intersections	OBJECT Point	Intersection points. If there are intersections, an empty list is returned. If the shape combination is not supported, nil is returned.

Sample

intersections = Shape3D.getIntersectionPoints(shape1, shape2)

getLineParameters()

Short description

Get two 3D points on the line. Note that these two points may not be the same points used for creating a line using the createLine() function as the line representation is normalized internally.

Parameters
Name	Type	Description
line	CONST_OBJECT Shape3D	The 3D line.

Return values
Name	Type	Description
point1	OBJECT Point	First 3D point on the line.
point2	OBJECT Point	Second 3D point on the line.

Sample

point1, point2 = Shape3D.getLineParameters(line)

getLineSegmentParameters()

Short description

Get the 3D end points of the line segment.

Parameters
Name	Type	Description
lineSegment	CONST_OBJECT Shape3D	The 3D line segment.

Return values
Name	Type	Description
point1	OBJECT Point	First 3D endpoint on the line segment.
point2	OBJECT Point	Second 3D endpoint on the line segment.

Sample

point1, point2 = Shape3D.getLineSegmentParameters(lineSegment)

getPlaneDistance()

Short description

Returns the minimum and maximum distance from all points on the shape to the reference plane. Distances are measured orthogonal to the reference plane. The query shape should have finite size.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape3D	The shape to check distance to.
referencePlane	CONST_OBJECT Shape3D	The reference plane.

Return values
Name	Type	Description
minDist	FLOAT	The distance from the plane to the closest point on the shape, or nil if projection failed.
maxDist	FLOAT	The orthogonal distance from the plane to the point on the shape furthest away from the plane, or nil if projection failed.

Sample

minDist, maxDist = Shape3D.getPlaneDistance(shape, referencePlane)

getPlaneParameters()

Short description

Get the parameters of the plane (normal vector plus distance). The distance is signed and measured from the origin along the normal. A plane where the normal points from the plane towards the origin has a negative distance.

Parameters
Name	Type	Description
plane	CONST_OBJECT Shape3D	The plane.

Return values
Name	Type	Description
nx	FLOAT	X component of plane normal vector.
ny	FLOAT	Y component of plane normal vector.
nz	FLOAT	Z component of plane normal vector.
distance	FLOAT	Distance from the origin to the plane along the plane normal.

Sample

nx, ny, nz, distance = Shape3D.getPlaneParameters(plane)

getPlanePoints()

Short description

Returns the point(s) on the plane at the given x,y-coordinate(s).

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape	Input plane.
points2d	CONST_OBJECT Point	Query points.

Return values
Name	Type	Description
points3d	OBJECT Point	Points on plane, nil if any error occurred.

Sample

points3d = Shape3D.getPlanePoints(shape, points2d)

getPolygonParameters()

Short description

Get the points defining the polygon.

Parameters
Name	Type	Description
polygon	CONST_OBJECT Shape3D	The polygon.

Return values
Name	Type	Description
points	OBJECT Point	Corner points for the polygon.

Sample

points = Shape3D.getPolygonParameters(polygon)

getPolylineParameters()

Short description

Get the points defining the polyline.

Parameters
Name	Type	Description
polyline	CONST_OBJECT Shape3D	The polyline.

Return values
Name	Type	Description
points	OBJECT Point	Corner points for the polyline.

Sample

points = Shape3D.getPolylineParameters(polyline)

getRectangleParameters()

Short description

Get the size and pose of the 3D rectangle.

Parameters
Name	Type	Description
rectangle	CONST_OBJECT Shape3D	The 3D rectangle.

Return values
Name	Type	Description
sizeX	FLOAT	Size of the rectangle in the x-direction before transformation (width).
sizeY	FLOAT	Size of the rectangle in the y-direction before transformation (height).
poseTransform	OBJECT Transform	Transform defining the rectangle position and orientation in 3D space. Is of type identity, translation or rigid.

Sample

sizeX, sizeY, poseTransform = Shape3D.getRectangleParameters(rectangle)

getSphereParameters()

Short description

Get the radius and position of the sphere.

Parameters
Name	Type	Description
sphere	CONST_OBJECT Shape3D	The sphere.

Return values
Name	Type	Description
radius	FLOAT	Radius of the sphere.
poseTransform	OBJECT Transform	Transform defining the sphere position and orientation in 3D space. Is of type identity, translation or rigid.

Sample

radius, poseTransform = Shape3D.getSphereParameters(sphere)

getType()

Short description

Get the shape type.

Parameters
Name	Type	Description
shape3d	CONST_OBJECT Shape3D	3D shape input.

Return values
Name	Type	Description
shapeType	ENUM Shape3DType	The shape type.

Sample

shapeType = Shape3D.getType(shape3d)

getVolume()

Short description

Returns the volume of the shape.

Parameters
Name	Type	Description
shape3d	CONST_OBJECT Shape3D	3D shape input.

Return values
Name	Type	Description
volume	FLOAT	The volume of the shape.

Sample

volume = Shape3D.getVolume(shape3d)

isClosed()

Short description

Returns true if the shape has no endpoints and encloses an area.

Parameters
Name	Type	Description
shape3d	CONST_OBJECT Shape3D	3D shape input.

Return values
Name	Type	Description
closed	BOOL	True if the shape is closed.

Sample

closed = Shape3D.isClosed(shape3d)

isZeroVolume()

Short description

Returns true if the shape type in general has no volume, such as for 2D shapes in 3D space.

Parameters
Name	Type	Description
shape3d	CONST_OBJECT Shape3D	3D shape input.

Return values
Name	Type	Description
noVolume	BOOL	True if the shape has zero volume.

Sample

noVolume = Shape3D.isZeroVolume(shape3d)

projectZ()

Short description

Projects one or more Shape3D orthogonally onto the plane described by z = 0. Returns the result as one or more Shape2D together with the minimum and maximum z-values encountered. Lines, line segments, circles, ellipses, boxes, rectangles, spheres, polygons and polylines are supported.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape3D	Shape(s) to be projected.

Return values
Name	Type	Description
projectedShape	OBJECT Shape	The projected shape(s), or nil if projection failed.
zMin	FLOAT	Minimum z-value(s) of shape(s) before projection, or nil if projection failed.
zMax	FLOAT	Maximum z-value(s) of shape(s) before projection, or nil if projection failed.

Sample

projectedShape, zMin, zMax = Shape3D.projectZ(shape)

rotateX()

Short description

Rotate the shape around an axis parallel to the world x-axis. The rotation center is optional. If not provided, the nominal center of the shape is used. For most shapes, this is the same point as the center of gravity. For cones, the nominal center is the center of the base circle. For lines and planes, the nominal center is the point in the shape closest to the origin.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape3D	Input shape
rotationAngle	FLOAT	The rotation angle in radians
rotationCenter	CONST_OBJECT Point	The rotation center. The nominal center of the shape is used if unspecified.

Return values
Name	Type	Description
outputShape	OBJECT Shape3D	The rotated shape, or nil if the input shape is invalid.

Sample

outputShape = Shape3D.rotateX(shape, rotationAngle, rotationCenter)

rotateY()

Short description

Rotate the shape around an axis parallel to the world y-axis. The rotation center is optional. If not provided, the nominal center of the shape is used. For most shapes, this is the same point as the center of gravity. For cones, the nominal center is the center of the base circle. For lines and planes, the nominal center is the point in the shape closest to the origin.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape3D	Input shape
rotationAngle	FLOAT	The rotation angle in radians
rotationCenter	CONST_OBJECT Point	The rotation center. The nominal center of the shape is used if unspecified.

Return values
Name	Type	Description
outputShape	OBJECT Shape3D	The rotated shape, or nil if the input shape is invalid.

Sample

outputShape = Shape3D.rotateY(shape, rotationAngle, rotationCenter)

rotateZ()

Short description

Rotate the shape around an axis parallel to the world z-axis. The rotation center is optional. If not provided, the nominal center of the shape is used. For most shapes, this is the same point as the center of gravity. For cones, the nominal center is the center of the base circle. For lines and planes, the nominal center is the point in the shape closest to the origin.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape3D	Input shape
rotationAngle	FLOAT	The rotation angle in radians
rotationCenter	CONST_OBJECT Point	The rotation center. The nominal center of the shape is used if unspecified.

Return values
Name	Type	Description
outputShape	OBJECT Shape3D	The rotated shape, or nil if the input shape is invalid.

Sample

outputShape = Shape3D.rotateZ(shape, rotationAngle, rotationCenter)

toLine()

Short description

Extends a line segment to the the infinite line type.

Parameters
Name	Type	Description
shape3d	CONST_OBJECT Shape3D	A line segment 3D shape.

Return values
Name	Type	Description
line	OBJECT Shape3D	The extended shape as a line.

Sample

line = Shape3D.toLine(shape3d)

toPixelRegion()

Short description

Projects the convex hull of a Shape3D (except polyLine) onto the plane z = 0 (in world coordinates) and creates the corresponding pixel region. The minimum and maximum world coordinate extent of the convex hull in the z-direction are returned. The reference image defines the pixel coordinate system to be used for the PixelRegion.

Keywords

draw, project, render, rasterize

See also

Image.PixelRegion

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape3D	The shape used to define the pixel region.
referenceImage	CONST_OBJECT Image	An image defining the coordinate system used to create the PixelRegion.
fill	BOOL	Set to true to generate a filled region, false to generate a border region. Non-closed shapes will always generate a border only.

Return values
Name	Type	Description
pixelRegion	OBJECT Image.PixelRegion	The projected convex hull region, or nil on error.
zMin	FLOAT	The minimum z-position of any part of the shape, in image world coordinates.
zMax	FLOAT	The maximum z-position of any part of the shape, in image world coordinates.

Sample

pixelRegion, zMin, zMax = Shape3D.toPixelRegion(shape, referenceImage)

toPlane()

Short description

Returns the plane which a flat shape span, such as rectangles, circles and polygons. Not defined for a line type shape.

Parameters
Name	Type	Description
shape3d	CONST_OBJECT Shape3D	A flat 3D shape input.

Return values
Name	Type	Description
plane	OBJECT Shape3D	The plane containing the flat 3D shape.

Sample

plane = Shape3D.toPlane(shape3d)

toPolygon()

Short description

Approximates a flat closed shape in 3D as a polygon.

Parameters
Name	Type	Description
shape	CONST_OBJECT Shape3D	Shape to be approximated.
epsilon	FLOAT	Maximum approximation error in the polygon approximation.
maxPoints	INT	Maximum number of points to use in the approximation (default is 1000). This is a stronger requirement than the epsilon and puts a limit on the function memory usage.

Return values
Name	Type	Description
polygon	OBJECT Shape3D	The shape as a polygon, or nil if the shape is invalid or non-flat.

Sample

polygon = Shape3D.toPolygon(shape, epsilon, maxPoints)

toString()

Short description

Get a user-friendly string description of the 3D shape.

Parameters
Name	Type	Description
shape3d	CONST_OBJECT Shape3D	3D shape input.

Return values
Name	Type	Description
str	STRING	User-friendly string description.

Sample

print(Shape3D.toString(shape3d))

transform()

Short description

Transforms a single shape or a vector of shapes according to the supplied transform. The transform must not change the type of the geometric primitive, e.g., it is not possible to transform a sphere using an affine transform as the result may not be a sphere anymore. The pose transform of shapes are kept as non-mirroring rigid transforms, made to always generate a right-handed orthonormal local coordinate system. Transforming a shape with a similarity transform will decompose the transform and apply the scaling component directly to the size of the shape. Similarly, a transform containing a mirroring component will be reformulated to get the mirroring aligned with a symmetry plane of the shape, where it has no effect on the shape and will be removed. Thus the shape will be correctly transformed, however fetching the pose transform of a shape may not return the transform used to transform the shape.

Parameters
Name	Type	Description
shape3d	CONST_OBJECT Shape3D	3D shape input.
transform	CONST_OBJECT Transform	The transform to apply.

Return values
Name	Type	Description
transformedShape	OBJECT Shape3D	The transformed shape.

Sample

transformedShape = Shape3D.transform(shape3d, transform)

translate()

Short description

Translate the shape, i.e., shift it along the x,y,z directions.

Parameters
Name	Type	Description
shape3d	CONST_OBJECT Shape3D	3D shape input.
translationX	FLOAT	The translation along the X-axis.
translationY	FLOAT	The translation along the Y-axis.
translationZ	FLOAT	The translation along the Z-axis.

Return values
Name	Type	Description
outputShape	OBJECT Shape3D	The translated shape, or nil if the input shape is invalid.

Sample

outputShape = Shape3D.translate(shape3d, translationX, translationY, translationZ)

Statistics

Short description

Functions for computing statistics of 1D numeric arrays, signals, time series, histograms etc. For example mean, standard deviation, correlation, comparing histograms. More functions for 1D data analysis is under the Profile API.

Overview

compareHistograms(), normalizeHistogram()

Functions

compareHistograms()

Short description

Compare two histograms of equal size. If the histograms are obtained from regions of different sizes, they should be normalized first.

Parameters
Name	Type	Description
histogram1	FLOAT	First histogram to compare
histogram2	FLOAT	Second histogram to compare
method	ENUM HistogramCompareMethod	Comparison method (default is Chi-squared statistic)

Return values
Name	Type	Description
distance	FLOAT	Distance measure of the two histograms. Zero if they are equal and larger the more different the histograms are.

Sample

distance = Statistics.compareHistograms(histogram1, histogram2)

normalizeHistogram()

Short description

Normalize a histogram. If no bin centers are specified, the histogram is normalized such that the sum of all values is 1. If centers is specified, it is instead normalized such that the integral over the value domain is 1.

Parameters
Name	Type	Description
inputHistogram	FLOAT	Input histogram
centers	FLOAT	Optional bin centers. Must be equally spaced. Typically, the bin centers are returned from the method that produced the histogram in the first place.

Return values
Name	Type	Description
outputHistogram	FLOAT	Output histogram, normalized to unit sum

Sample

outputHistogram = Statistics.normalizeHistogram(inputHistogram)

TCPIPClient

Short description

Provides raw TCIP/IP connections to servers. First a new TCPIPClient needs to be created using the create function. Afterwards the IP address and the port must be set using the set-functions. Then a call to the connect-function starts the connection tries to the server. If the connection gets disconnected it is tried to established it again automatically. Connects and disconnects can be detected by a register to the OnConnect and OnDisconnect events or by polling the IsConnected function. Failed transmits are a sign of broken connection and user could also call disconnect manually. Data could be transmitted to the server using the "transmit" function. Data could be received by a register to the "OnReceive" event or by calling the blocking receive()-function. The transmitted and received data is raw data. It could get automatically framed for transmitting and receiving can be automatically parsed if setting a framing with the "setFraming" function. If a framing is set, there is a fix buffer size of receiving and transmitting which is 10240 bytes per default and can be changed using the setFramingBufferSize()-function. Every data packet which is larger than this will be discarded.

Keywords

Ethernet

Overview

connect(), create(), deregister(), disconnect(), isConnected(), receive(), register(), setFraming(), setFramingBufferSize(), setIPAddress(), setInterface(), setPort(), setReceiveQueueSize(), setStaticSourcePort(), setTransmitTimeout(), transmit()

OnConnected, OnDisconnected, OnReceive

Functions

connect()

Short description

Starts trying to connect to the server. The OnConnected and OnDisconnected events are thrown every time the connection gets connected or disconnected. If the client gets disconnected, the client automatically tries to reconnect every 5 seconds in the background. So the connect function does not need to be called in OnDisconnect.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
timeoutMs	INT	The timeout to wait initially until the client gets connected. If not set, 500ms is the default. Check IsConnected afterwards if was successful.

Sample

TCPIPClient.connect(handle)

create()

Short description

Creates a new TCP/IP client instance. Client stays active as long as this handle exists.

Return values
Name	Type	Description
handle	HANDLE	The instance handle of the TCP/IP Client

Sample

handle = TCPIPClient.create()

deregister()

Short description

This function is used to deregister from any registered event of the handle.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
eventname	STRING	The event to deregister from
callback	STRING	The function name which was registered on the event

Return values
Name	Type	Description
success	BOOL	True if successfully deregistered. False if event does not exist or callback wasn’t registered.

disconnect()

Short description

Forces a disconnect from the server

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the TCP/IP Client

Sample

TCPIPClient.disconnect(handle)

isConnected()

Short description

Returns true if the client is connected

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the TCP/IP Client

Return values
Name	Type	Description
isConnected	BOOL	True if the client is connected

Sample

bConnected = TCPIPClient.isConnected(handle)

receive()

Short description

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the TCP/IP Client
timeout	INT	Timeout in ms to wait for received data. 0 is default and means directly return.

Return values
Name	Type	Description
data	BINARY	The data which was received

Sample

local data = TCPIPClient.receive(handle, 1000)

register()

Short description

This function is used to register for any event of the handle.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
eventname	STRING	The event to register to
callback	STRING	The function name to call on the event occurrence

Return values
Name	Type	Description
success	BOOL	True if successfully registered. False if event does not exist.

setFraming()

Short description

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the TCP/IP Client
rxStart	BINARY	Start framing for receiving, could be empty string. Maximum size of 9.
rxStop	BINARY	Stop framing for receiving. If empty then all raw data is received. Maximum size of 9.
txStart	BINARY	Start framing for sending, could be empty string. Maximum size of 9.
txStop	BINARY	Stop framing for sending, could be empty string. Maximum size of 9.

Sample

TCPIPClient.setFraming(handle, "\02", "\03", "", "\013\010") -- STX...ETX for receiving and ...CR/LF for transmitting

setFramingBufferSize()

Short description

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the TCP/IP Client
rxBufSize	INT	The new framing buffer size for framed receiving.
txBufSize	INT	The new framing buffer size for framed transmitting.

Sample

TCPIPClient.setFramingBufferSize(handle, 21000, 21000)

setIPAddress()

Short description

Sets the server ip address to connect to

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the TCP/IP Client
ipAddress	STRING	The IP Address as string e.g. '192.168.0.10'

Sample

TCPIPClient.setIPAddress(handle, "127.0.0.1")

setInterface()

Short description

Sets the interface to use for connecting.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the TCP/IP Client
ifName	ENUM EthernetInterfaces	One of the available interfaces

Sample

TCPIPClient.setInterface(handle, "ETH1")

setPort()

Short description

Sets the server port to connect to.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the TCP/IP Client
port	INT	The server port between 1 and 65535

Sample

TCPIPClient.setPort(handle, 2120)

setReceiveQueueSize()

Short description

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the TCP/IP Client
queueSize	INT	The new receive queue size.
bDiscardIfFull	BOOL	Set to true to discard the newest item which is currently added instead of discarding the oldest element. Default is false.
warnOverruns	BOOL	Set to false to disable warning on overruns when using the receive()-function. Default is true.

Sample

TCPIPClient.setReceiveQueueSize(handle, 50)

setStaticSourcePort()

Short description

Sets a static source port for the TCP/IP client. If this function is not used, the default behavior of the operating system is to select a free source port automatically. Do not use this function unless a custom protocol requires a static client port.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the TCP/IP Client
port	INT	The client source port between 1 and 65535

Sample

TCPIPClient.setStaticSourcePort(handle, 2120)

setTransmitTimeout()

Short description

Sets the timeout for transmits in milliseconds.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the TCP/IP Client
timeoutMs	INT	The timeout for transmits in milliseconds.

Sample

TCPIPClient.setTransmitTimeout(handle, 5000)

transmit()

Short description

Transmits data to the server. If framing is set using the "setFraming" function, then the framing characters are automatically prefixed and suffixed to the transmitted data. Blocks until data has been transmitted. If transmit fails the return number of transmitted bytes is zero. If transmit fails the connection might be broken. The TCPIPClient would connect automatically again, but the user could also call disconnect()+connect() functions manually.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the TCP/IP Client
data	BINARY	The data which is to be transmitted

Return values
Name	Type	Description
numberOfBytesTransmitted	INT	Number of bytes transmitted; 0 if transmit failed

Sample

TCPIPClient.transmit(handle,"Hello Server")

Events

OnConnected

Short description

The on connected event which is thrown for every connect.

Parameters
Name	Type	Description
handle	HANDLE	This is a handle event and must be registered on the handle

OnDisconnected

Short description

The on disconnected event which is thrown for every disconnect. The client automatically tries to connect again every 5 seconds, so the connect() function does not need to be called here.

Parameters
Name	Type	Description
handle	HANDLE	This is a handle event and must be registered on the handle

OnReceive

Short description

The on receive event which is thrown for every new received data.

Parameters
Name	Type	Description
handle	HANDLE	This is a handle event and must be registered on the handle
data	BINARY	The received data

TCPIPServer

Short description

Provides possibility to open new TCP/IP server ports at the device. A TCP/IP Server must be created using the create-function and a port must be set using the setPort-function. After a call to the listen-function the server waits for new incoming connections. If new connections arrive, the "OnConnectionAccepted" event is thrown. The user has to call then the accept function to accept the connection. Every accepted connection has its one connection handle. On the connection handle the user could receive and transmit. Currently the number of maximum parallel connections is set to 10 per default and can be changed over the setMaxConnections-function. Further connections will be automatically rejected. If new data arrives on the connection, the "OnReceive" event of the TCP/IP server is thrown with the connection handle, which received data, and the received data as parameter. The connection can be closed by the server side by calling the "TCPIPServer.Connection.close" function. If the connection is closed by the peer or by the server side, the "OnConnectionClosed" event is thrown with the connection handle of the closed connection. The transmitted and received data is raw data. It could get automatically framed for transmitting and receiving can be automatically parsed if setting a framing with the "setFraming" function. If a framing is set, there is a fix buffer size of receiving and transmitting which is 10240 bytes per default and can be changed using the setFramingBufferSize()-function. Every data packet which is larger than this will be discarded.

Keywords

Ethernet

Overview

create(), deregister(), listen(), register(), setFraming(), setFramingBufferSize(), setInterface(), setMaxConnections(), setPort(), setTransmitTimeout()

OnConnectionAccepted, OnConnectionClosed, OnReceive

Functions

create()

Short description

Creates a new TCP/IP server instance. Server stays active as long as this handle exists.

Return values
Name	Type	Description
handle	HANDLE	The instance handle of the TCP/IP Server

Sample

handle = TCPIPServer.create()

deregister()

Short description

This function is used to deregister from any registered event of the handle.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
eventname	STRING	The event to deregister from
callback	STRING	The function name which was registered on the event

Return values
Name	Type	Description
success	BOOL	True if successfully deregistered. False if event does not exist or callback wasn’t registered.

listen()

Short description

Starts listening for new connections on the port. Remember to register for new connections before calling this function. If port or framing is changed, this function needs to be called to apply the settings and wait for connections on the changed port. The OnConnectionClosed function is called for existing accepted connections.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the TCP/IP Server

Return values
Name	Type	Description
success	BOOL	Returns true if the listening on the port was successful

Sample

TCPIPServer.listen(handle)

register()

Short description

This function is used to register for any event of the handle.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
eventname	STRING	The event to register to
callback	STRING	The function name to call on the event occurrence

Return values
Name	Type	Description
success	BOOL	True if successfully registered. False if event does not exist.

setFraming()

Short description

Sets the framing which is to be used. If not set the default framing is no framing (raw byte/packet-wise connection). Framing could be also explicitly disabled by calling this function with 2 empty binary data for rx and tx. One framing part could be maximum size of 9 bytes. If a framing is set, there is a fix buffer size of receiving and transmitting which is 10240 bytes per default and can be changed using the setFramingBufferSize()-function. Every data packet which is larger than this will be discarded. The listen function has to be called afterwards so that the setting gets active.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the TCP/IP Server
rxStart	BINARY	Start framing for receiving, could be empty string. Maximum size of 9.
rxStop	BINARY	Stop framing for receiving. If empty then all raw data is received. Maximum size of 9.
txStart	BINARY	Start framing for sending, could be empty string. Maximum size of 9.
txStop	BINARY	Stop framing for sending, could be empty string. Maximum size of 9.

Sample

TCPIPServer.setFraming(handle, "\02", "\03", "", "\013\010") -- STX...ETX for receiving and ...CR/LF for transmitting

setFramingBufferSize()

Short description

Sets the size of the internal framing parser buffer which is used if there is a rx or tx framing set using the setFraming function. If the rx or tx framing isn’t set, its buffer size has no effect. This size is the maximum size of a packet which can be parsed by the framing. The size is used for start and stop framing. Default is 10240 bytes. The listen function has to be called afterwards so that the setting gets active

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the TCP/IP Server
rxBufSize	INT	The new framing buffer size for framed receiving.
txBufSize	INT	The new framing buffer size for framed transmitting.

Sample

TCPIPServer.setFramingBufferSize(handle, 21000, 21000)

setInterface()

Short description

Sets the interface to use for listening. The listen function has to be called afterwards so that the setting gets active.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the TCP/IP Server
ifName	ENUM EthernetInterfaces	One of the available interfaces

Sample

TCPIPServer.setInterface(handle, "ETH1")

setMaxConnections()

Short description

Sets the number of maximum parallel active connections. Further active connections are automatically discarded. The default is set to 10 connections. The listen function has to be called afterwards so that the setting gets active.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the TCP/IP Server
maxCons	INT	The max number of parallel active connections.

Sample

TCPIPServer.setMaxConnections(handle, 5)

setPort()

Short description

Sets the server port which is to be used. The listen function has to be called afterwards so that the setting gets active.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the TCP/IP Server
port	INT	The server port between 1 and 65535

Sample

TCPIPServer.setPort(handle, 2120)

setTransmitTimeout()

Short description

Sets the timeout for transmits in milliseconds.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the TCP/IP Server
timeoutMs	INT	The timeout for transmits in milliseconds.

Sample

TCPIPServer.setTransmitTimeout(handle, 5000)

Events

OnConnectionAccepted

Short description

This event is thrown for every new connection which was accepted. The new connection is hold until the connected peer disconnects or the connection is rejected. To reject a connection, the function Connection.close can be called.

Parameters
Name	Type	Description
handle	HANDLE	This is a handle event and must be registered on the handle
conHandle	HANDLE	The connection handle of the connection which is opened

OnConnectionClosed

Short description

This event is thrown if a connection is closed by the connected peer. The connection handle is not usable anymore. The event is not thrown if the Connection.close function was called.

Parameters
Name	Type	Description
handle	HANDLE	This is a handle event and must be registered on the handle
conHandle	HANDLE	The connection handle of the connection which is closed

OnReceive

Short description

The on receive event which is thrown for every new received data.

Parameters
Name	Type	Description
handle	HANDLE	This is a handle event and must be registered on the handle
conHandle	HANDLE	The connection handle of the connection which is closed
data	BINARY	The received data. If a framing is set, only contains the content without the framing.

TCPIPServer.Connection

Short description

Controls one connection of the TCP/IP Server. To close the connection just set the handle to nil.

Overview

close(), getPeerAddress(), isConnected(), transmit()

Functions

close()

Short description

Closes the connection explicitly from the server side. The OnConnectionClosed event is not thrown.

Parameters
Name	Type	Description
conHandle	HANDLE	The instance handle of the TCP/IP Server connection

Sample

TCPIPServer.Connection.close(conHandle)

getPeerAddress()

Short description

Returns the IP address and port of the connected peer on this connection.

Parameters
Name	Type	Description
conHandle	HANDLE	The instance handle of the TCP/IP Server connection

Return values
Name	Type	Description
ipAddr	STRING	The IP address of the connected peer. Nil if not available.
portNo	INT	The port number of the connected peer. Nil if not available.

Sample

local ip, port = TCPIPServer.Connection.getPeerAddress(conHandle)

isConnected()

Short description

Returns true if the client connection is still connected

Parameters
Name	Type	Description
conHandle	HANDLE	The instance handle of the TCP/IP Server connection

Return values
Name	Type	Description
isConnected	BOOL	True if the client is connected

Sample

local bConnected = TCPIPServer.Connection.isConnected(conHandle)

transmit()

Short description

Transmits data to the clients. If framing is set using the "setFraming" function, then the framing characters are automatically prefixed and suffixed to the transmitted data. Blocks until data has been transmitted.

Parameters
Name	Type	Description
conHandle	HANDLE	The instance handle of the TCP/IP Server connection
data	BINARY	The data which is to be transmitted

Return values
Name	Type	Description
numberOfBytesTransmitted	INT	Number of bytes transmitted; 0 if transmit failed

Sample

TCPIPServer.Connection.transmit(conHandle, "Hello Server")

Text

Short description

Iconic object used for displaying text in a View. Deprecated, please use plain strings and a TextDecoration object instead.

Overview

create(), setPosition(), setSize(), setText()

Functions

create()

Short description

Creates a new Text.

Return values
Name	Type	Description
text	OBJECT Text	A new text

Sample

text = Text.create()

setPosition()

Short description

Set the text position.

Parameters
Name	Type	Description
text	OBJECT Text	The instance to be used.
posX	INT	X
posY	INT	Y
posZ	INT	Z (only useful if 3D viewer is used).

Sample

Text.setPosition(text, 10, 10)

setSize()

Short description

Set the font size.

Parameters
Name	Type	Description
text	OBJECT Text	The instance to be used.
fonSize	INT	The font size.
lineSpacing	FLOAT	The line spacing in % of the font-size. Default is 1.1

Sample

Text.setSize(text, 10)

setText()

Short description

Set the textual content.

Parameters
Name	Type	Description
text	OBJECT Text	The instance to be used.
textstring	STRING	The text

Sample

Text.setText(text, "This is a text.")

Timer

Short description

Provides Timers which can expire and call automatically callbacks. Timers can run once or automatically periodic

Overview

create(), deregister(), register(), setExpirationTime(), setPeriodic(), start(), stop()

OnExpired

Functions

create()

Short description

Sets up a timer with a specific expiration timer time after which the specified callback function is called automatically. Timer needs to be started explicitly.

Return values
Name	Type	Description
handle	HANDLE	Unique handle for the timer

Sample

handle = Timer.create()

deregister()

Short description

This function is used to deregister from any registered event of the handle.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
eventname	STRING	The event to deregister from
callback	STRING	The function name which was registered on the event

Return values
Name	Type	Description
success	BOOL	True if successfully deregistered. False if event does not exist or callback wasn’t registered.

register()

Short description

This function is used to register for any event of the handle.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
eventname	STRING	The event to register to
callback	STRING	The function name to call on the event occurrence

Return values
Name	Type	Description
success	BOOL	True if successfully registered. False if event does not exist.

setExpirationTime()

Short description

Sets the expiration time of the timer in milliseconds. Default is 5000. New time is used next time calling start().

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
timeMS	INT	The expire time of the timer in milliseconds. Must be greater than 0.

Sample

Timer.setExpirationTime(handle, 5000)

setPeriodic()

Short description

Sets the timer to periodic. Default is not periodic.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
isPeriodic	BOOL	True if timer occurs periodically until it is stopped or destroyed. Default is false.

Sample

Timer.setPeriodic(handle, true)

start()

Short description

Starts the timer

Parameters
Name	Type	Description
handle	HANDLE	The instance to use

Sample

Timer.start(handle)

stop()

Short description

Stops the timer

Parameters
Name	Type	Description
handle	HANDLE	The instance to use

Sample

Timer.stop(handle)

Events

OnExpired

Short description

This event is thrown every time the timer expires

Parameters
Name	Type	Description
handle	HANDLE	This is a handle event and must be registered on the handle

Sample

Timer.register(handle, "OnExpired", "handleExpired")

Transform

Short description

Object representing a linear transform in 2D or 3D space.

Functions

clone()

Short description

Duplicates the transform.

Parameters
Name	Type	Description
transform	CONST_OBJECT Transform	The instance to use

Return values
Name	Type	Description
clone	OBJECT Transform	The duplicated transform

Sample

local clonedTransform = Transform.clone(transform)

compose()

Short description

Composes two transforms of the same dimensionality.

Parameters
Name	Type	Description
transformA	CONST_OBJECT Transform	The instance to use
transformB	CONST_OBJECT Transform	The instance to use

Return values
Name	Type	Description
composedTransform	OBJECT Transform	The composed transformation matrix.

Sample

local composedTransform = Transform.compose(transformA, transformB)

createFromMatrix2D()

Short description

Creates a 2D transform directly from a 3x3 matrix representation.

Parameters
Name	Type	Description
matrix	CONST_OBJECT Matrix	A 3x3 matrix with the transform.
desiredType	ENUM TransformType	The desired transform type. If the numerical properties of the matrix does not fit the desired type, nil is returned. Optional, if not specified, the transform type is found by a numerical evaluation of the matrix.

Return values
Name	Type	Description
transform	OBJECT Transform	The new 2D transform.

Sample

local transform = Transform.createFromMatrix2D(matrix, desiredType)

createFromMatrix3D()

Short description

Creates a 3D transform directly from a 4x4 matrix representation.

Parameters
Name	Type	Description
matrix	CONST_OBJECT Matrix	A 4x4 matrix with the transform.
desiredType	ENUM TransformType	The desired transform type. If the numerical properties of the matrix does not fit the desired type, nil is returned. Optional, if not specified, the transform type is found by a numerical evaluation of the matrix.

Return values
Name	Type	Description
transform	OBJECT Transform	The new 3D transform.

Sample

local transform = Transform.createFromMatrix3D(matrix, desiredType)

createHomography2D()

Short description

Creates a 2D homography/projective transform.

Parameters
Name	Type	Description
matrix	CONST_OBJECT Matrix	A 3x3 matrix with the full homography transform.

Return values
Name	Type	Description
homographyTransform	OBJECT Transform	The new 2D homography transform

Sample

local homographyTransform = Transform.createHomography2D(matrix)

createHomography2DFromPoints()

Short description

Creates a homography/projective transform from N corresponding point pairs, source and destination points need to be of equal length. If more than 4 points are given an RANSAC estimation of the homography is performed. If either margin or iterations is set to zero all points provided will be used.

Parameters
Name	Type	Description
srcPoints	CONST_OBJECT Point	N source points.
dstPoints	CONST_OBJECT Point	N destination points.
margin	FLOAT	Margin expressed in world-units. Points which after transformation is within the margin is considered as inliers. Default value is 1.0. If the certainty of the points is high the margin can be lowered to reject more outliers.
iterations	INT	Number of iterations in the RANSAC loop in the homography estimation. Default value is 100. If set to 0 a least-squares estimation is performed.

Return values
Name	Type	Description
homographyTransform	OBJECT Transform	Homography transform.

Sample

local homographyTransform = Transform.createHomography2DFromPoints(srcPoints, dstPoints, margin, iterations)

createHomography3D()

Short description

Creates a 3D homography/projective transform.

See also

Transform.createHomography2D

Parameters
Name	Type	Description
matrix	CONST_OBJECT Matrix	A 4x4 matrix with the full homography transform.

Return values
Name	Type	Description
homographyTransform	OBJECT Transform	The new 3D homography transform

Sample

local homographyTransform = Transform.createHomography3D(matrix)

createIdentity2D()

Short description

Creates a new 2D transform with no rotation, scale or translation.

See also

Transform.createIdentity3D

Return values
Name	Type	Description
transform	OBJECT Transform	The new 2D identity transform

Sample

local transform = Transform.createIdentity2D()

createIdentity3D()

Short description

Creates a new 3D transform with no rotation, scale or translation.

See also

Transform.createIdentity2D

Return values
Name	Type	Description
transform	OBJECT Transform	The new 3D identity transform

Sample

local transform = Transform.createIdentity3D()

createReflection2D()

Short description

Creates a 2D rigid transform that is a reflection in the given 2D line.

Keywords

mirror

See also

Transform.createRigid2D

Parameters
Name	Type	Description
line	CONST_OBJECT Shape	The reflection 2D line.

Return values
Name	Type	Description
reflection	OBJECT Transform	The new 2D reflection transform which is of RIGID type.

Sample

local reflection = Transform.createReflection2D(line)

createReflection3D()

Short description

Creates a 3D rigid transform that is a reflection in the given 3D plane.

See also

Transform.createRigid3D

Parameters
Name	Type	Description
plane	CONST_OBJECT Shape3D	The reflection 3D plane.

Return values
Name	Type	Description
reflection	OBJECT Transform	The new 3D reflection transform which is of RIGID type.

Sample

local reflection = Transform.createReflection3D(plane)

createRigid2D()

Short description

Creates a 2D rigid transform with only rotation and translation.

Parameters
Name	Type	Description
rotation	FLOAT	Counter clockwise rotation (in radians)
xTrans	FLOAT	Translation in the x direction
yTrans	FLOAT	Translation in the y direction
origin	CONST_OBJECT Point	Optional origin of rotation if other than (0,0)

Return values
Name	Type	Description
rigidTransform	OBJECT Transform	The new 2D rigid transform

Sample

local rigidTransform = Transform.createRigid2D(math.pi/2, xTrans, yTrans, origin)

createRigidAxisAngle3D()

Short description

Creates a 3D rigid transform by defining an axis, a rotation around the axis and a translation.

Parameters
Name	Type	Description
axis	FLOAT	The rotation axis to rotate about.
rotation	FLOAT	Clockwise rotation when looking along the axis (in radians)
xTrans	FLOAT	Translation in the x direction
yTrans	FLOAT	Translation in the y direction
zTrans	FLOAT	Translation in the z direction
origin	CONST_OBJECT Point	Optional origin of rotation if other than (0,0,0)

Return values
Name	Type	Description
rigidTransform	OBJECT Transform	The new 3D rigid transform

Sample

local rigidTransform = Transform.createRigidAxisAngle3D({xAxis, yAxis, zAxis}, rotation, xTrans, yTrans, zTrans, origin)

createRigidEuler3D()

Short description

Creates a 3D rigid transform using Euler angles and translation. Rotations are parameterized and applied in the order specified by the rotation order. E.g. using order "XYZ", the object is first rotated alpha radians around the world x-axis, then beta radians around the world y-axis, and finally gamma radians around the world z-axis. All rotations are according to the right hand rule, positive is clockwise when looking along the direction of the rotation axis.

Parameters
Name	Type	Description
rotationOrder	ENUM RotationOrder	Order in which to apply rotations and order of rotation parameters.
alpha	FLOAT	Rotation around the first axis (in radians).
beta	FLOAT	Rotation arond the second axis (in radians).
gamma	FLOAT	Rotation around the third axis (in radians).
xTrans	FLOAT	Translation in the x direction.
yTrans	FLOAT	Translation in the y direction.
zTrans	FLOAT	Translation in the z direction.
origin	CONST_OBJECT Point	Optional origin of rotation if other than (0,0,0).

Return values
Name	Type	Description
rigidTransform	OBJECT Transform	The new 3D rigid transform

Sample

local rigidTransform = Transform.createRigidEuler3D(rotationOrder, alpha, beta, gamma, xTrans, yTrans, zTrans, origin)

createScaling2D()

Short description

Creates a 2D scaling transform which scales in the x- and y-dimensions.

Parameters
Name	Type	Description
xScale	FLOAT	Scaling in the x direction
yScale	FLOAT	Optional scaling in the y direction. If omitted the same scaling will be used in both x and y direction.
origin	CONST_OBJECT Point	Optional origin of scaling if other than (0,0)

Return values
Name	Type	Description
transform	OBJECT Transform	The new 2D scaling transform which is of type SIMILARITY

Sample

local transform = Transform.createScaling2D(xScale, yScale, origin)

createScaling3D()

Short description

Creates a 3D scaling transform which scales in the x-, y-, and z-dimensions.

Parameters
Name	Type	Description
xScale	FLOAT	Scaling in the x direction
yScale	FLOAT	Optional scaling in the y direction. If omitted the scaling for the x direction will also be used in the y direction.
zScale	FLOAT	Optional scaling in the z direction. If omitted the scaling for the x direction will also be used in the z direction.
origin	CONST_OBJECT Point	Optional origin of scaling if other than (0,0)

Return values
Name	Type	Description
transform	OBJECT Transform	The new 3D scaling transform which is of type SIMILARITY

Sample

local transform = Transform.createScaling3D(xScale, yScale, zScale, origin)

createSimilarity2D()

Short description

Creates a 2D similarity transform with rotation, scale and translation.

Parameters
Name	Type	Description
rotation	FLOAT	Counter clockwise rotation (in radians)
scale	FLOAT	Scale factor
xTrans	FLOAT	Translation in the x direction
yTrans	FLOAT	Translation in the y direction
origin	CONST_OBJECT Point	Optional origin of rotation if other than (0,0)

Return values
Name	Type	Description
similarityTransform	OBJECT Transform	The new 2D similarity transform

Sample

local similarityTransform = Transform.createSimilarity2D(math.pi/2, scale, xTrans, yTrans, origin)

createTranslation2D()

Short description

Creates a 2D translational transform.

Parameters
Name	Type	Description
xTrans	FLOAT	Translation in the x direction
yTrans	FLOAT	Translation in the y direction

Return values
Name	Type	Description
transform	OBJECT Transform	The new 2D translational transform

Sample

local transform = Transform.createTranslation2D(xTrans, yTrans)

createTranslation3D()

Short description

Creates a 3D translational transform.

Parameters
Name	Type	Description
xTrans	FLOAT	Translation in the x direction
yTrans	FLOAT	Translation in the y direction
zTrans	FLOAT	Translation in the z direction

Return values
Name	Type	Description
transform	OBJECT Transform	The new 3D translational transform

Sample

local transform = Transform.createTranslation3D(xTrans, yTrans, zTrans)

decomposeRigid2D()

Short description

Decomposes a 2D rigid transform into rotation and translation components. The transform must not contain a reflection.

Parameters
Name	Type	Description
rigidTransform	CONST_OBJECT Transform	The 2D rigid transform.

Return values
Name	Type	Description
rotation	FLOAT	Counter clockwise rotation (in radians).
xTrans	FLOAT	Translation in the x direction.
yTrans	FLOAT	Translation in the y direction.

Sample

local rotation, xTrans, yTrans = Transform.decomposeRigid2D(rigidTransform)

decomposeRigidEuler3D()

Short description

Decomposes a 3D rigid transform into Euler angles and translation. Rotations are parameterized and applied in the order specified by the rotation order. E.g. to recreate a transformation decomposed using "ZYX" rotation order, first rotate alpha around the world z-axis, then beta around the world y-axis and finally gamma around the world x-axis. All rotations are according to the right hand rule, positive is clockwise when looking along the direction of the rotation axis. The transform must not contain a reflection.

See also

Transform.createRigidEuler3D

Parameters
Name	Type	Description
rigidTransform	CONST_OBJECT Transform	The 3D rigid transform.
rotationOrder	ENUM RotationOrder	Order in which to apply rotations and order of the returned rotation parameters.

Return values
Name	Type	Description
alpha	FLOAT	Rotation around the first axis (in radians).
beta	FLOAT	Rotation arond the second axis (in radians).
gamma	FLOAT	Rotation around the third axis (in radians).
xTrans	FLOAT	Translation in the x direction.
yTrans	FLOAT	Translation in the y direction.
zTrans	FLOAT	Translation in the z direction.

Sample

local alpha, beta, gamma, xTrans, yTrans, zTrans = Transform.decomposeRigidEuler3D(rigidTransform, rotationOrder)

decomposeSimilarity2D()

Short description

Decomposes a similarity transform into a rigid transform and a scale factor. The similarity transform can be reconstructed by first scaling and then applying the rigid transformation.

See also

Transform.decomposeRigid2D

Parameters
Name	Type	Description
similarityTransform	CONST_OBJECT Transform	The 2D similarity transform.

Return values
Name	Type	Description
scale	FLOAT	Scale factor.
rigidTransform	OBJECT Transform	The rigid part of the transform.

Sample

local scale, rigidTransform = Transform.decomposeSimilarity2D(similarityTransform)

decomposeSimilarity3D()

Short description

Decomposes a similarity transform into a rigid transform and a scale factor. The similarity transform can be reconstructed by first scaling and then applying the rigid transformation.

See also

Transform.decomposeRigidEuler3D

Parameters
Name	Type	Description
similarityTransform	CONST_OBJECT Transform	The 3D similarity transform.

Return values
Name	Type	Description
scale	FLOAT	Scale factor.
rigidTransform	OBJECT Transform	The rigid part of the transform.

Sample

local scale, rigidTransform = Transform.decomposeSimilarity3D(similarityTransform)

decomposeTranslation2D()

Short description

Decomposes a 2D translation transform into translation components.

See also

Transform.decomposeRigid2D

Parameters
Name	Type	Description
translationTransform	CONST_OBJECT Transform	The 2D translation transform.

Return values
Name	Type	Description
xTrans	FLOAT	Translation in the x direction.
yTrans	FLOAT	Translation in the y direction.

Sample

local xTrans, yTrans = Transform.decomposeTranslation2D(translationTransform)

decomposeTranslation3D()

Short description

Decomposes a 3D translation transform into translation components.

See also

Transform.decomposeRigid3D

Parameters
Name	Type	Description
translationTransform	CONST_OBJECT Transform	The 3D translation transform.

Return values
Name	Type	Description
xTrans	FLOAT	Translation in the x direction.
yTrans	FLOAT	Translation in the y direction.
zTrans	FLOAT	Translation in the z direction.

Sample

local xTrans, yTrans, zTrans = Transform.decomposeTranslation3D(translationTransform)

getMatrix()

Short description

Returns the transform matrix.

Parameters
Name	Type	Description
transform	CONST_OBJECT Transform	The instance to use

Return values
Name	Type	Description
matrix	OBJECT Matrix	The full 3x3 or 4x4 matrix of this transform.

Sample

local matrix = Transform.getMatrix(transform)

getType()

Short description

Returns the transform type

Parameters
Name	Type	Description
transform	CONST_OBJECT Transform	The transform to check

Return values
Name	Type	Description
result	ENUM TransformType	The transform type

Sample

            if (Transform.getType(transform)=="IDENTITY") then
              doSomething()
            end

invert()

Short description

Returns the inverse transform.

Parameters
Name	Type	Description
transform	CONST_OBJECT Transform	The instance to use

Return values
Name	Type	Description
inversedTransform	OBJECT Transform	The inverse transformation matrix.

Sample

local inversedTransform = Transform.invert(transform)

rotate2D()

Short description

Returns a 2D transform with a counter clockwise rotation appended to the input transform. The rotation center is optional. If not provided, the world origin is used.

See also

Transform.rotateY, Transform.rotateX

Parameters
Name	Type	Description
inputTransform	CONST_OBJECT Transform	Input 2D transform.
rotationAngle	FLOAT	The rotation angle in radians.
rotationCenter	CONST_OBJECT Point	The rotation center. Default is the origin.

Return values
Name	Type	Description
outputTransform	OBJECT Transform	The transform with appended rotation.

Sample

outputTransform = Transform.rotate2D(inputTransform, rotationAngle, rotationCenter)

rotateX()

Short description

Returns a 3D transform with a rotation around an axis parallel to the world x-axis appended to the input transform. The rotation center is optional. If not provided, the world origin is used. Positive rotation is according to the right hand rule, clockwise when looking along the direction of the rotation axis.

Parameters
Name	Type	Description
inputTransform	CONST_OBJECT Transform	Input 3D transform.
rotationAngle	FLOAT	The rotation angle in radians.
rotationCenter	CONST_OBJECT Point	The rotation center. Default is the origin.

Return values
Name	Type	Description
outputTransform	OBJECT Transform	The transform with appended rotation.

Sample

outputTransform = Transform.rotateX(inputTransform, rotationAngle, rotationCenter)

rotateY()

Short description

Returns a 3D transform with a rotation around an axis parallel to the world y-axis appended to the input transform. The rotation center is optional. If not provided, the world origin is used. Positive rotation is according to the right hand rule, clockwise when looking along the direction of the rotation axis.

Parameters
Name	Type	Description
inputTransform	CONST_OBJECT Transform	Input 3D transform.
rotationAngle	FLOAT	The rotation angle in radians.
rotationCenter	CONST_OBJECT Point	The rotation center. Default is the origin.

Return values
Name	Type	Description
outputTransform	OBJECT Transform	The transform with appended rotation.

Sample

outputTransform = Transform.rotateY(inputTransform, rotationAngle, rotationCenter)

rotateZ()

Short description

Returns a 3D transform with a rotation around an axis parallel to the world z-axis appended to the input transform. The rotation center is optional. If not provided, the world origin is used. Positive rotation is according to the right hand rule, clockwise when looking along the direction of the rotation axis.

Parameters
Name	Type	Description
inputTransform	CONST_OBJECT Transform	Input 3D transform.
rotationAngle	FLOAT	The rotation angle in radians.
rotationCenter	CONST_OBJECT Point	The rotation center. Default is the origin.

Return values
Name	Type	Description
outputTransform	OBJECT Transform	The transform with appended rotation.

Sample

outputTransform = Transform.rotateZ(inputTransform, rotationAngle, rotationCenter)

scale2D()

Short description

Returns a 2D transform with a scaling appended to the input transform.

See also

Transform.createScaling2D

Parameters
Name	Type	Description
inputTransform	CONST_OBJECT Transform	Input 2D transform.
scaleFactor	FLOAT	The scaling factor to apply.
scaleCenter	CONST_OBJECT Point	The scaling center, remains fixed during scaling. Default is the origin.

Return values
Name	Type	Description
outputTransform	OBJECT Transform	The transform with appended scaling.

Sample

outputTransform = Transform.scale2D(inputTransform, scaleFactor)

scale3D()

Short description

Returns a 3D transform with a scaling appended to the input transform.

See also

Transform.createScaling3D

Parameters
Name	Type	Description
inputTransform	CONST_OBJECT Transform	Input 3D transform.
scaleFactor	FLOAT	The scaling factor to apply.
scaleCenter	CONST_OBJECT Point	The scaling center, remains fixed during scaling. Default is the origin.

Return values
Name	Type	Description
outputTransform	OBJECT Transform	The transform with appended scaling.

Sample

outputTransform = Transform.scale3D(inputTransform, scaleFactor)

to3D()

Short description

Converts a 2D transform to a 3D transform. The created 3D transform applies the 2D transform to the x,y-coordinates and leaves the z-coordinates unchanged. This holds up to affine transformations. For homographies, the final scaling of the points is applied also to the z-coordinate.

See also

Transform.toType

Parameters
Name	Type	Description
transform2d	CONST_OBJECT Transform	The 2D source transform.

Return values
Name	Type	Description
transform3d	OBJECT Transform	The corresponding 3D transform. Nil is returned if input is invalid.

Sample

local transform3d Transform.to3D(transform2d)

toString()

Short description

Get a string representation of the transform. The matrix representing the transform is written row-wise.

Parameters
Name	Type	Description
transform	CONST_OBJECT Transform	Input transform

Return values
Name	Type	Description
str	STRING	String representation of the transform

Sample

print("The transform is: " .. transform:toString())

toType()

Short description

Returns a copy of the transformation marked as desired type. If the desired type is not general enough to support the actual transformation, nil is returned. The transform itself is not changed. Converting to a more general type always succeeds.

See also

Transform.to3D

Parameters
Name	Type	Description
transform	CONST_OBJECT Transform	The source transform.
desiredType	ENUM TransformType	The desired transform type, e.g., RIGID, SIMILARITY, AFFINE, TRANSLATION.

Return values
Name	Type	Description
convertedTransform	OBJECT Transform	The transform of the desired type, or nil if the desired type was not compatible with the actual transform.

Sample

local convertedTransform Transform.toType(transform, "RIGID")

translate2D()

Short description

Returns a 2D transform with a translation in world coordinates appended to the input transform.

Parameters
Name	Type	Description
inputTransform	CONST_OBJECT Transform	Input 2D transform.
xTrans	FLOAT	The translation along the x-axis.
yTrans	FLOAT	The translation along the y-axis.

Return values
Name	Type	Description
outputTransform	OBJECT Transform	The transform with appended translation.

Sample

outputTransform = Transform.translate2D(inputTransform, xTrans, yTrans)

translate3D()

Short description

Returns a 3D transform with a translation in world coordinates appended to the input transform.

See also

Transform.createRigidEuler3D

Parameters
Name	Type	Description
inputTransform	CONST_OBJECT Transform	Input 3D transform.
xTrans	FLOAT	The translation along the x-axis.
yTrans	FLOAT	The translation along the y-axis.
zTrans	FLOAT	The translation along the z-axis.

Return values
Name	Type	Description
outputTransform	OBJECT Transform	The transform with appended translation.

Sample

outputTransform = Transform.translate3D(inputTransform, xTrans, yTrans, zTrans)

TriSpector

Short description

TriSpectorP specific functionality.

Overview

getLaserEnabled(), readTriSpector1000Heightmap(), setLaserEnabled()

Functions

getLaserEnabled()

Short description

Returns true if the laser is on.

Return values
Name	Type	Description
enabled	BOOL	true if the laser is on.

Sample

enabled = TriSpector.getLaserEnabled()

readTriSpector1000Heightmap()

Short description

Read the TriSpector1000 image format (png).

Parameters
Name	Type	Description
path	STRING	Path to input file

Return values
Name	Type	Description
heightImage	OBJECT Image	Height map
reflectanceImage	OBJECT Image	Reflectance image

Sample

heightImage, reflectanceImage = TriSpector.readTriSpector1000Heightmap("resources/image.png")

setLaserEnabled()

Short description

Turn laser on or off.

Parameters
Name	Type	Description
enable	BOOL	true to turn laser on, false to turn it off.

Sample

TriSpector.setLaserEnabled(true)

UDPSocket

Short description

Provides functionality for sending/receiving UDP packets. First a new UDPSocket needs to be created using the create function. Afterwards it could be set to a specified interface using setInterface()-function. Then a call to the bind-function binds the udp socket to a port and transmit calls and OnReceive events are possible. If bind()-function is not called, the socket is bind implicitly to the first transmit target. Data could be transmitted to the server using the "transmit" function. Data could be received by a register to the "OnReceive" event or by calling the blocking receive()-function.

Overview

bind(), create(), deregister(), receive(), register(), setInterface(), setReceiveQueueSize(), transmit()

OnReceive

Functions

bind()

Short description

Binds the socket to a specific local port.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the UDP socket
port	INT	The port to bind to

Return values
Name	Type	Description
success	BOOL	True if socket was bound successfully, false if an error occurred.

Sample

success = UDPSocket.bind(handle, 10000)

create()

Short description

Creates a UDP socket instance.

Return values
Name	Type	Description
handle	HANDLE	The instance handle of the UDP socket

Sample

handle = UDPSocket.create()

deregister()

Short description

This function is used to deregister from any registered event of the handle.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
eventname	STRING	The event to deregister from
callback	STRING	The function name which was registered on the event

Return values
Name	Type	Description
success	BOOL	True if successfully deregistered. False if event does not exist or callback wasn’t registered.

receive()

Short description

Receives one UDP packet with a specified timeout. The socket must be bound first either explicitly by calling bind or implicitly by a preceding transmit. If timeout is zero then it directly returns without any return values. Incoming data between multiple receive calls is queued per message. There is a fix receive queue size of 10 packets per default and can be changed using the setReceiveQueueSize()-function. More data is discarded.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the UDP socket
timeout	INT	Timeout in ms to wait for received data. 0 is default and means directly return.

Return values
Name	Type	Description
data	BINARY	The received data
ipAddress	STRING	The peer address the data was received from
port	INT	The peer port the data was received from

register()

Short description

This function is used to register for any event of the handle.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
eventname	STRING	The event to register to
callback	STRING	The function name to call on the event occurrence

Return values
Name	Type	Description
success	BOOL	True if successfully registered. False if event does not exist.

setInterface()

Short description

Sets the interface to bind the socket to.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the UDP socket
ifName	ENUM EthernetInterfaces	One of the available interfaces

Sample

UDPSocket.setInterface(handle, "ETH1")

setReceiveQueueSize()

Short description

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the UDP socket
queueSize	INT	The new receive queue size.
bDiscardIfFull	BOOL	Set to true to discard the newest item which is currently added instead of discarding the oldest element. Default is false.
warnOverruns	BOOL	Set to false to disable warning on overruns when using the receive()-function. Default is true.

Sample

UDPSocket.setReceiveQueueSize(handle, 50)

transmit()

Short description

Transmit a UDP packet to the specified peer. This will trigger an implicit bind if the socket has not been bound yet.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the UDP socket
ipAddress	STRING	The ip address to transmit to
port	INT	The port to transmit to
data	BINARY	The data which to be transmitted

Return values
Name	Type	Description
numberOfBytesTransmitted	INT	Number of bytes transmitted; 0 if transmit failed

Sample

transmitted = UDPSocket.transmit(handle, "192.168.0.1", 10000, "Hello world")

Events

OnReceive

Short description

The event which is triggered when data is received on the socket. The socket must be bound first either explicitly by calling bind or implicitly by a preceding transmit. For each packet receive there is one event thrown.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle of the UDP socket
data	BINARY	The received data packet
ipAddress	STRING	The peer address the data was received from
port	INT	The peer port the data was received from

View

Short description

Provides view function for iconics like Text, Scan, Image and PointCloud.

Functions

add()

Short description

Adds the iconics, with an optional decoration, to be shown in viewers when View.present is called. If the decoration is omitted a default decoration is used. Iconics are stored by reference, if they are modified between View.add and View.present, only their latest state will be presented. This function is deprecated. Use View.addXYZ instead. Reasons for deprecation: type-safety, missing parent-id leads to usage of wrong coordinate-systems.

Parameters
Name	Type	Description
handle	HANDLE	The instance to be used.
iconics	CONST_AUTO	The iconic or list of iconics to be viewed.
decoration	CONST_OBJECT [API:DataFormat:]	Optional decoration for the iconics.

Sample

View.add(handle, iconics, decoration)

addGraph()

Short description

Adds a graph to be shown in viewers when View.present is called. The graph type, e.g., xy-plot or histogram, is set by the GraphDecoration object. If the parentId refers to an Image, the graph will be drawn relative to its coordinate system. If no parent is given, it is drawn relative to the world coordinate system.

Parameters
Name	Type	Description
handle	HANDLE	The instance to be used.
values	FLOAT	A vector of float values to be plotted on the y-axis of the graph.
coordinates	FLOAT	Optional vector of float values for the x-axis, e.g., time, position etc. The default value is an empty vector, in which case the integer indexes of the value vector are used.
decoration	CONST_OBJECT View.GraphDecoration	Optional decoration for the graph.
iconicId	STRING	Optional iconic id.
parentId	STRING	Optional parent id.

Return values
Name	Type	Description
iconicId	STRING	Iconic id. An id is generated if not provided.

Sample

iconicId = View.addGraph(handle, values, coordinates, decoration, iconicId)

addHeightmap()

Short description

Adds an Image that is shown as a heightmap in viewers when View.present is called. If a list of images is used, the first image will be presented as the heightmap. Consecutive images are used as selectable view-components (textures) for the heightmap using the labels from the labels list argument.

Parameters
Name	Type	Description
handle	HANDLE	The instance to be used.
images	CONST_OBJECT Image	The heightmap to be viewed. Additional images will be used as selectable view components.
decorations	CONST_OBJECT View.ImageDecoration	Optional decorations for the image(s).
labels	STRING	Optional labels for the additional images
iconicId	STRING	Optional iconic id.
parentId	STRING	Optional parent id. The same parent id is used for all added images.

Return values
Name	Type	Description
iconicId	STRING	Iconic id. An id is generated if not provided.

Sample

iconicId = View.addHeightmap(handle, {heightmap, reflectance}, {reflectanceDecoration}, {"Reflectance"}, "heightmap1")

addImage()

Short description

Adds one or more Image to be shown in viewers when View.present is called.

Parameters
Name	Type	Description
handle	HANDLE	The instance to be used.
image	CONST_OBJECT Image	The image(s) to be viewed.
decoration	CONST_OBJECT View.ImageDecoration	Optional decoration for the image(s).
iconicId	STRING	Optional iconic id(s). One iconic id per image must be supplied if this parameter is used.
parentId	STRING	Optional parent id. The same parent id is used for all added images.

Return values
Name	Type	Description
iconicId	STRING	A (vector of) iconic id(s). Id(s) are generated if not provided.

Sample

iconicId = View.addImage(handle, image, imageDecoration, "image1")

addMesh()

Short description

Adds one or more Meshes to be shown in viewers when View.present is called.

Parameters
Name	Type	Description
handle	HANDLE	The instance to be used.
mesh	OBJECT Mesh	The mesh(es) to be viewed.
decoration	CONST_OBJECT View.MeshDecoration	Optional decoration for the mesh(es).
iconicId	STRING	Optional iconic id(s). One iconic id per mesh must be supplied if this parameter is used.
parentId	STRING	Optional parent id. The same parent id is used for all added meshes.

Return values
Name	Type	Description
iconicId	STRING	A (vector of) iconic id(s). Id(s) are generated if not provided.

Sample

iconicId = View.addMesh(handle, mesh, decoration, "mesh1")

addPixelRegion()

Short description

Adds one or more Image.PixelRegion to be shown as an overlay for an iconic or separately when View.present is called. If a parentId is given, the PixelRegion is displayed as a clipped overlay for the given parent, otherwise it is drawn separately in world-coordinates.

See also

Image.drawPixelRegion

Parameters
Name	Type	Description
handle	HANDLE	The instance to be used.
pixelRegion	CONST_OBJECT Image.PixelRegion	The pixel region(s) to be viewed.
decoration	CONST_OBJECT View.PixelRegionDecoration	Optional decoration for the pixel region(s). The same decoration is used for all added pixel regions.
iconicId	STRING	Optional iconic id(s). One iconic id per pixel region must be supplied if this parameter is used.
parentId	STRING	Optional parent id. The same parent id is used for all added pixel regions.

Return values
Name	Type	Description
iconicId	STRING	A (vector of) iconic id(s). Id(s) are generated if not provided.

Sample

iconicId = View.addPixelRegion(handle, pixelRegion, pixelRegionDecoration, "pixelRegion1", "image1")

addPoint()

Short description

Adds one or more Point objects to be shown in viewers when View.present is called. If the parentId refers to an Image, the point will be drawn relative to its coordinate system. If no parent is given, it is drawn relative to the world coordinate system.

See also

Image.drawPoint

Parameters
Name	Type	Description
handle	HANDLE	The instance to be used.
point	CONST_OBJECT [API:DataFormat:]	The point(s) which is to be viewed.
decoration	CONST_OBJECT View.ShapeDecoration	Optional decoration for the point. The same decoration is used for all added points. N.B: A ShapeDecoration shall be used, there is no dedicated decoration only for Points.
iconicId	STRING	Optional iconic id(s). One iconic id per point must be supplied if this parameter is used.
parentId	STRING	Optional parent id. The same parent id is used for all added points.

Return values
Name	Type	Description
iconicId	STRING	A (vector of) iconic id(s). Id(s) are generated if not provided.

Sample

iconicId = View.addPoint(handle, point, shapeDecoration, "point1", "image1")

addPointCloud()

Short description

Adds one or more PointClouds to be shown in viewers when View.present is called.

Parameters
Name	Type	Description
handle	HANDLE	The instance to be used.
pointCloud	CONST_OBJECT PointCloud	The point cloud(s) to be viewed.
decoration	CONST_OBJECT View.PointCloudDecoration	Optional decoration for the point cloud(s).
iconicId	STRING	Optional iconic id(s). One iconic id per point cloud must be supplied if this parameter is used.
parentId	STRING	Optional parent id. The same parent id is used for all added pointClouds.

Return values
Name	Type	Description
iconicId	STRING	A (vector of) iconic id(s). Id(s) are generated if not provided.

Sample

iconicId = View.addPointCloud(handle, pointCloud, pointCloudDecoration, "pointcloud1")

addProfile()

Short description

Adds one or more profiles to be shown in viewers when View.present is called. The visualization properties are specified using a GraphDecoration object. If the parentId refers to an Image, the profile will be drawn relative to its coordinate system. If no parent is given, it is drawn relative to the world coordinate system.

Parameters
Name	Type	Description
handle	HANDLE	The instance to be used.
profile	OBJECT Profile	The profile(s) to be viewed.
decoration	CONST_OBJECT View.GraphDecoration	Optional decoration for the profile.
iconicId	STRING	Optional iconic id(s). One iconic id per profile must be supplied if this parameter is used.
parentId	STRING	Optional parent id. The same parent id is used for all added profiles.

Return values
Name	Type	Description
iconicId	STRING	A (vector of) iconic id(s). Id(s) are generated if not provided.

Sample

iconicId = View.addProfile(handle, profile, decoration, iconicId)

addShape()

Short description

Adds either one or more Shape/Shape3D objects to be shown in viewers when View.present is called. If the parentId refers to an Image, the shape will be drawn relative to its coordinate system. If no parent is given, it is drawn relative to the world coordinate system.

See also

Image.drawShape

Parameters
Name	Type	Description
handle	HANDLE	The instance to be used.
shape	CONST_OBJECT [API:DataFormat:]	The shape(s)/point(s) which is to be viewed.
decoration	CONST_OBJECT View.ShapeDecoration	Optional decoration for the shape. The same decoration is used for all added shapes.
iconicId	STRING	Optional iconic id(s). One iconic id per shape must be supplied if this parameter is used.
parentId	STRING	Optional parent id. The same parent id is used for all added shapes.

Return values
Name	Type	Description
iconicId	STRING	A (vector of) iconic id(s). Id(s) are generated if not provided.

Sample

iconicId = View.addShape(handle, shape, shapeDecoration, "shape1", "image1")

addText()

Short description

Adds a string to be drawn when View.present is called. If the parentId refers to an Image, the text will be drawn relative to its coordinate system. If no parent is given, it is drawn relative to the world coordinate system.

See also

Image.drawText

Parameters
Name	Type	Description
handle	HANDLE	The instance to be used.
text	STRING	The text which is to be viewed.
decoration	CONST_OBJECT View.TextDecoration	Optional decoration for the text.
iconicId	STRING	Optional iconic id.
parentId	STRING	Optional parent id.

Return values
Name	Type	Description
iconicId	STRING	Iconic id. An id is generated if not provided.

Sample

iconicId = View.addText(handle, "Hello world", textDecoration, "text1", "image1")

clear()

Short description

Removes all previously added iconics from viewers when View.present is called.

Parameters
Name	Type	Description
handle	HANDLE	The instance to be used.

Sample

View.clear(handle)

countConnections()

Short description

Returns the number of connected viewers at this viewer’s identifier. If no identifier is set, it counts all connected viewers on all identifiers.

Parameters
Name	Type	Description
handle	HANDLE	The instance to be used.

Return values
Name	Type	Description
connectedCount	INT	The number of connected viewers or 0 if none is connected.

create()

Short description

Creates a new View.

Parameters
Name	Type	Description
id	STRING	Optional viewer identifier which is used to select dedicated viewers.

Return values
Name	Type	Description
handle	HANDLE	The new View

Sample

viewer = View.create()

deregister()

Short description

This function is used to deregister from any registered event of the handle.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
eventname	STRING	The event to deregister from
callback	STRING	The function name which was registered on the event

Return values
Name	Type	Description
success	BOOL	True if successfully deregistered. False if event does not exist or callback wasn’t registered.

installEditor()

Short description

Installs an editor for the specified iconic so that it can be edited in viewers. The editor is available after calling View.present. When an iconic is changed by an editor the View.OnChange event is published.

Parameters
Name	Type	Description
handle	HANDLE	The instance to be used.
iconicId	STRING	ID of the iconic for which to install an editor.

Sample

View.installEditor(handle, "shape1")

present()

Short description

Updates registered viewers with changes to the View. This lets viewers - show iconics added with any of the View.add-functions - make editors (added with View.installEditor) available - remove (View.remove) or clear (View.clear) iconics. The Channel parameter is optional and defaults to LIVE. In overload situations, ASSURED means that present calls will be queued and LIVE means that older present calls will be discarded.

Parameters
Name	Type	Description
handle	HANDLE	The instance to be used.
channel	ENUM Channel	The channel on which to transmit the presented iconics. Default value is LIVE.

Sample

View.present(handle, "LIVE")

rasterize()

Short description

Generates a 2D color image by rasterizing Shapes, Points, PixelRegions and Text as overlays into the pixels of a previously added image. The base image to rasterize into is taken to be the last added image using View.addImage or View.addHeightmap. Any subsequent calls to View.addShape, View.addPoint, View.addPixelRegion, View.addText, View.addPointCloud are used to add overlay graphics into the base image by modifying the pixel values in this image. This results in an image similar to what is shown in the viewer. Note however that this function does not have the full capacity as the external viewer typically has, so there will be differences. The main limitations are as follows: * 3D scenes cannot be reproduced, e.g., 3D pointcloud or mesh visualizations cannot be generated. * The resolution of the generated graphics is limited by the image rasterized into. * For text rendering there is a more limited set of ASCII characters supported compared to the external viewer. Moreover, rotated text is not currently supported. View.rasterize must be called prior to View.present as this latter function clears the internal list of objects inside the viewer instance. For each overlay iconic type there are also restrictions in terms of capacity compared to an external viewer. The support and limitations are as described below. Base image: The base image to draw on is defined to the last call by either by View.addImage or View.addHeightMap. Any pixel type is supported, e.g., UINT8, UINT16, FLOAT32. Grayscale images will be converted to RGB using a colormap. If the image is UINT8 without missing data a grayscale RGB image is generated. Otherwise the colormap 'JET' is used for conversion to RGB. To select a custom color map use the colormap ID in the View.ImageDecoration object when adding the image to the viewer. See details further down. The View.addHeightmap takes both a range image and an intensity image as input. To select which of these images to use there is a channelIndex input parameter to View.rasterize. Overlay support and restrictions: * PixelRegion - Fully supported using the provided decoration object. Full decoration support. * Shape - Supported as rasterized versions without any anti-aliasing. Full decoration support. * Point - Supported as rasterized versions without any anti-aliasing. Full decoration support. * Text - Supported with approximate mapping to the text rendered in the viewer. A limited ASCII-set is supported, i.e., not all characters will be rendered. Not all properties in the TextDecoration object are supported. * PointCloud - Partial support. Points are rendered over their x,y-coordinates in the image. The same colormaps are available as for the Image type. The following iconics are not supported: Mesh, Profile, Graph, Scan The colors for the rasterized image or pointcloud can be selected by the colormap ID in the View.ImageDecoration.setColormap or conversely in the View.PointCloudDecoration.setZColormap functions. This ID is mapped to the View.ColorMap.fromMap enums in the following order: 'AUTUMN', 'BLUE_WHITE_RED', 'COOL', 'GRAY', 'HOT', 'HSV', 'JET', 'RAINBOW', 'SPRING', 'SUMMER', 'THERMAL', 'TRAFFIC_LIGHT', 'WINTER', 'RGB'. Default is zero which attempts to mimic the default viewer behavior. Set 1 to get 'AUTUMN' and -1 to get an inverted 'AUTUMN' colorization.

Keywords

color, jpeg, jpg, png, render, draw

Parameters
Name	Type	Description
viewer	HANDLE	The viewer instance to rasterize.
channelIndex	INT	Only relevant when View.addHeightMap was used to add the base image. Default is 0, which means that the heightmap/range image is used as base image. Set 1 to use the reflectance/intensity image instead.

Return values
Name	Type	Description
image	OBJECT Image	Rasterized color RGB image. Nil on failure.

Sample

local image = View.rasterize(viewer)

register()

Short description

This function is used to register for any event of the handle.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
eventname	STRING	The event to register to
callback	STRING	The function name to call on the event occurrence

Return values
Name	Type	Description
success	BOOL	True if successfully registered. False if event does not exist.

remove()

Short description

Removes the iconic with the given id from viewers when View.present is called.

Parameters
Name	Type	Description
handle	HANDLE	The instance to be used.
iconicId	STRING	Id of the iconic to remove.

Sample

View.remove(handle, iconicId)

setDefaultDecoration()

Short description

Sets a default decoration, e.g., ShapeDecoration or ImageDecoration, that will be used in successive calls to view() and add() if the optional decoration argument is omitted.

Parameters
Name	Type	Description
handle	HANDLE	The instance to be used.
decoration	OBJECT [API:DataFormat:]	Decoration object that will be set as default.

Sample

View.setDefaultDecoration(handle, decoration)

setFillColor()

Short description

Sets the fill color of the default ShapeDecoration. This function is deprecated, please use View.ShapeDecoration.setFillColor instead.

Parameters
Name	Type	Description
handle	HANDLE	The instance to be used.
red	INT	Red
green	INT	Green
blue	INT	Blue
alpha	INT	Alpha

Sample

View.setFillColor(handle, 255, 0, 0, 255)

setID()

Short description

Set the viewer identifier in order to select dedicated viewers.

Parameters
Name	Type	Description
handle	HANDLE	The instance to be used.
id	STRING	The identifier.

Sample

View.setID(handle, "Viewer1")

setLineColor()

Short description

Sets the line color of the default ShapeDecoration. This function is deprecated, please use View.ShapeDecoration.setLineColor instead.

Parameters
Name	Type	Description
handle	HANDLE	The instance to be used.
red	INT	Red
green	INT	Green
blue	INT	Blue

Sample

View.setLineColor(handle, 255, 0, 0)

setLineWidth()

Short description

Set the line width of the default ShapeDecoration. This function is deprecated, please use View.ShapeDecoration.setLineWidth instead.

Parameters
Name	Type	Description
handle	HANDLE	The instance to be used.
width	INT	The line thickness.

Sample

View.setLineWidth(handle, 1)

uninstallEditor()

Short description

Removes the editor from the specified iconic. The editor is removed from viewers after View.present after calling View.present.

Parameters
Name	Type	Description
handle	HANDLE	The instance to be used.
iconicId	STRING	ID of the iconic for which to uninstall an editor.

Sample

View.uninstallEditor(handle, "shape1")

updateCamera()

Short description

Updates the camera settings for the scene when View.present is called.

See also

View.present, View.Camera

Parameters
Name	Type	Description
handle	HANDLE	The instance to be used.
camera	OBJECT View.Camera	The camera to set.

Sample

View.updateCamera(handle, cam)

updateDecoration()

Short description

Updates the decoration of an already existing iconic when View.present is called. The type of the decoration must match the iconic.

Parameters
Name	Type	Description
handle	HANDLE	The instance to be used.
id	STRING	The identifier of the iconic.
decoration	OBJECT [API:DataFormat:]	Decoration object that will be used for the update.

Sample

View.updateDecoration(handle, "shape1", decoration)

updateTransform()

Short description

Updates the pose (position, orientation, scaling) with the given transform of an already existing iconic when View.present is called. It is up to the viewer what kind of transformations are valid.

See also

View.present, Transform

Parameters
Name	Type	Description
handle	HANDLE	The instance to be used.
id	STRING	The identifier.
transform	OBJECT Transform	Transformation applied to the given object.

Sample

View.updateTransform(handle, "shape1", transform)

view()

Short description

Shows the given iconics (e.g. images, results, etc.) in the available viewers. If the decoration is omitted a default decoration is used. This function is deprecated. Use View.addXYZ and View.present instead. Reasons for deprecation: performance issues, type-safety, missing parent-id leads to usage of wrong coordinate-systems.

Parameters
Name	Type	Description
handle	HANDLE	The instance to be used.
iconics	CONST_AUTO	The iconic or list of iconics to be viewed.
decoration	CONST_OBJECT [API:DataFormat:]	Optional decoration for the iconics.

Sample

View.view(handle, iconics, decoration)

Events

OnChange

Short description

This event is published when an Iconic is modified using an editor in the Viewer. Apps can register to this event to react to the changes, for example to update their representation of the object with the changes from the viewer.

Parameters
Name	Type	Description
handle	HANDLE	Instance handle of this view
iconicId	STRING	ID of the modified iconic
iconic	OBJECT [API:DataFormat:]	The modified iconic

OnConnect

Short description

This event is published when a Viewer has connected to the View. Apps can register to this event to perform actions in response to the connection.

Parameters
Name	Type	Description
handle	HANDLE	Instance handle of this view

OnPointer

Short description

This event is published when a user has interacted with a Viewer using the select tool. Apps can register to this event to receive the id of the iconic under the pointer (if any) and the type of action.

Parameters
Name	Type	Description
handle	HANDLE	Instance handle of this view
iconicId	STRING	The ID of the iconic under the pointer or an empty string if no iconic was hit.
pointerActionType	ENUM PointerActionType	Pointer action type
pointerType	ENUM PointerType	Pointer type

View.Camera

Short description

Camera object that describes camera properties for the scene in the viewer. To be set with View.setCamera().

Overview

create(), setPosition(), setTarget(), setUp()

Functions

create()

Short description

Creates a new View.Camera

Return values
Name	Type	Description
camera	HANDLE	The new camera

Sample

cam = View.Camera.create()

setPosition()

Short description

Set the position of the camera.

Parameters
Name	Type	Description
camera	HANDLE	The instance to be used.
posX	FLOAT	X
posY	FLOAT	Y
posZ	FLOAT	Z

Sample

View.Camera.setPosition(cam, 0, -1, 1000)

setTarget()

Short description

Set the target-vector of the camera.

Parameters
Name	Type	Description
camera	HANDLE	The instance to be used.
posX	FLOAT	X
posY	FLOAT	Y
posZ	FLOAT	Z

Sample

View.Camera.setTarget(cam, 0, 0, 0)

setUp()

Short description

Set the up-vector of the camera.

Parameters
Name	Type	Description
camera	HANDLE	The instance to be used.
posX	FLOAT	X
posY	FLOAT	Y
posZ	FLOAT	Z

Sample

View.Camera.setUp(cam, 0, 0, 1)

View.ColorMap

Short description

Create a custom LINEAR color gradient in which colors are specified as entries in a vector with RGBA.

Overview

addStop(), create(), fromMap(), setType(), toImage(), toString()

Functions

addStop()

Short description

Adds a color stop (value, R, G, B, A) to the ColorMap. If the value for a stop is outside the defined range, the stop is discarded.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
value	FLOAT	Represents a position between 0 and 1 at which a color for the gradient is defined. If the value equals the value of an existing color stop, the existing color stop is replaced.
red	INT	Red value in range (0, 255).
green	INT	Green value in range (0, 255).
blue	INT	Blue value in range (0, 255).
alpha	INT	Alpha/opacity component in range [0-255] (optional).

Sample

View.ColorMap.addStop(handle, 255, 0, 0)

create()

Short description

Create a new ColorMap.

Parameters
Name	Type	Description
rangeStart	FLOAT	Define the start of the value range. Default is 0.0 (optional).
rangeStop	FLOAT	Define the stop of the value range. Default is 1.0 (optional).

Return values
Name	Type	Description
handle	HANDLE	The new ColorMap

Sample

handle = View.ColorMap.create()

fromMap()

Short description

Create a gradient with predefined steps. The ColorMap will be cleared before.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
predefinedMap	ENUM PredefinedColorMap	Create a gradient with predefined steps.

Sample

View.ColorMap.fromMap(handle, "RAINBOW")

setType()

Short description

A enum value indicating whether the ColorMap makes DISCRETE color jumps, or smooth LINEAR transition between color stops.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
type	ENUM ColorMapType	ColorMap type

Sample

View.ColorMap.setType(handle, "DISCRETE")

toImage()

Short description

Convert the ColorMap to an image which represents the ColorMap from left to right.

Parameters
Name	Type	Description
handle	HANDLE	The instance handle to use
width	INT	Width of the image.
height	INT	Height of the image.

Return values
Name	Type	Description
image	OBJECT Image	The color map as image object.

Sample

image = View.ColorMap.toImage(handle, 100, 200)

toString()

Short description

Get a user-friendly string description of the ColorMap.

Parameters
Name	Type	Description
handle	CONST_OBJECT View.ColorMap	The ColorMap object.

Return values
Name	Type	Description
str	STRING	User-friendly description of the ColorMap.

Sample

str = View.ColorMap.toString(handle)

View.GraphDecoration

Short description

Decoration object that describes visualization properties for graphs. For example, the graph type such as xy-plot (LINE) or histogram (BAR) can be set, as well as colors, text labels, size properties etc.

Functions

create()

Short description

Creates a new GraphDecoration object.

Return values
Name	Type	Description
deco	OBJECT View.GraphDecoration	The new GraphDecoration

Sample

graphDecoration = View.GraphDecoration.create()

setAspectRatio()

Short description

Sets the graphs aspect ratio.

Parameters
Name	Type	Description
deco	OBJECT View.GraphDecoration	The instance to be used
type	ENUM AspectRatio	The graphs aspect ratio, EQUAL, SQUARE or FIT. Default value is FIT.

Sample

View.GraphDecoration.setAspectRatio(graphDecoration, "FIT")

setAxisColor()

Short description

Sets color of graph axes.

Parameters
Name	Type	Description
deco	OBJECT View.GraphDecoration	The instance to be used
red	INT	Red value in range [0,255]
green	INT	Green value in range [0,255]
blue	INT	Blue value in range [0,255]
a	INT	Alpha value in range [0,255]. Optional, default value is 255.

Sample

View.GraphDecoration.setAxisColor(graphDecoration, 255, 0, 0, 255)

setAxisVisible()

Short description

Sets whether to show or hide the axes.

Parameters
Name	Type	Description
deco	OBJECT View.GraphDecoration	The instance to be used
visible	BOOL	True if axis should be visible, default value is true.

Sample

View.GraphDecoration.setAxisVisible(graphDecoration, false)

setAxisWidth()

Short description

Sets the graphs axis line width.

Parameters
Name	Type	Description
deco	OBJECT View.GraphDecoration	The instance to be used
width	FLOAT	Axis width. The default value is 0, which lets the viewer automatically decide the size..

Sample

View.GraphDecoration.setAxisWidth(graphDecoration, 2.5)

setBackgroundColor()

Short description

Sets background color of the plot.

Parameters
Name	Type	Description
deco	OBJECT View.GraphDecoration	The instance to be used
red	INT	Red value in range [0,255]
green	INT	Green value in range [0,255]
blue	INT	Blue value in range [0,255]
a	INT	Alpha value in range [0,255]. Optional, default value is 255.

Sample

View.GraphDecoration.setBackgroundColor(graphDecoration, 255, 0, 0, 255)

setBackgroundVisible()

Short description

Sets whether the background should be visible or not.

Parameters
Name	Type	Description
deco	OBJECT View.GraphDecoration	The instance to be used
visible	BOOL	True if background should be visible, default value is true.

Sample

View.GraphDecoration.setBackgroundVisible(graphDecoration, false)

setDrawSize()

Short description

Sets the graph drawing size depending on the graph type set (size of points or width of lines or width of bars).

Parameters
Name	Type	Description
deco	OBJECT View.GraphDecoration	The instance to be used
size	FLOAT	Draw size. The default value is 0, which lets the viewer automatically decide the size.

Sample

View.GraphDecoration.setDrawSize(graphDecoration, 3)

setDynamicSizing()

Short description

Sets whether sizes should be dynamic and therefore independent from the zoom, or should be larger when zoomed in (default). Dynamic sizing also results in a dynamic tick distance, getting finer when zooming.

Parameters
Name	Type	Description
deco	OBJECT View.GraphDecoration	The instance to be used
dynamicSizing	BOOL	True if sizing should be dynamic instead of fixed, default value is false.

Sample

View.GraphDecoration.setDynamicSizing(graphDecoration, true)

setGraphColor()

Short description

Sets color of the graph lines, dots or bars.

Parameters
Name	Type	Description
deco	OBJECT View.GraphDecoration	The instance to be used
red	INT	Red value in range [0,255]
green	INT	Green value in range [0,255]
blue	INT	Blue value in range [0,255]
a	INT	Alpha value in range [0,255]. Optional, default value is 255.

Sample

View.GraphDecoration.setGraphColor(graphDecoration, 255, 0, 0, 255)

setGraphType()

Short description

Sets the graph type to draw lines, dots or bars.

Parameters
Name	Type	Description
deco	OBJECT View.GraphDecoration	The instance to be used
type	ENUM GraphType	The graph type, DOT, LINE or BAR. Default value is LINE.

Sample

View.GraphDecoration.setGraphType(graphDecoration, "BAR")

setGridColor()

Short description

Sets color of the grid lines.

Parameters
Name	Type	Description
deco	OBJECT View.GraphDecoration	The instance to be used
red	INT	Red value in range [0,255]
green	INT	Green value in range [0,255]
blue	INT	Blue value in range [0,255]
a	INT	Alpha value in range [0,255]. Optional, default value is 255.

Sample

View.GraphDecoration.setGridColor(graphDecoration, 255, 0, 0, 255)

setGridVisible()

Short description

Sets whether to show or hide the grid lines.

Parameters
Name	Type	Description
deco	OBJECT View.GraphDecoration	The instance to be used
visible	BOOL	True if grid should be visible, default value is true.

Sample

View.GraphDecoration.setGridVisible(graphDecoration, false)

setIndexCoordinates()

Short description

Sets whether to use the index in the value vector as x value or use the supplied coordinate vector.

Parameters
Name	Type	Description
deco	OBJECT View.GraphDecoration	The instance to be used
indexAsX	BOOL	True if index rather then the coordinate should be used as x value, default value is false.

Sample

View.GraphDecoration.setIndexCoordinates(graphDecoration, true)

setLabelColor()

Short description

Sets color of the text labels.

Parameters
Name	Type	Description
deco	OBJECT View.GraphDecoration	The instance to be used
red	INT	Red value in range [0,255]
green	INT	Green value in range [0,255]
blue	INT	Blue value in range [0,255]
a	INT	Alpha value in range [0,255]. Optional, default value is 255.

Sample

View.GraphDecoration.setLabelColor(graphDecoration, 255, 0, 0, 255)

setLabelSize()

Short description

Sets the text size of labels on the axes.

Parameters
Name	Type	Description
deco	OBJECT View.GraphDecoration	The instance to be used
size	FLOAT	Label text size. The default value is 0, which lets the viewer automatically decide the size.

Sample

View.GraphDecoration.setLabelSize(graphDecoration, 3)

setLabels()

Short description

Sets the label text of the x and y axes.

Parameters
Name	Type	Description
deco	OBJECT View.GraphDecoration	The instance to be used
xLabel	STRING	x-axis text label, empty by default.
yLabel	STRING	y-axis text label, empty by default.

Sample

View.GraphDecoration.setLabels(graphDecoration, "Time [ms]", "Quantity")

setLabelsVisible()

Short description

Sets whether to show or hide the axes labels.

Parameters
Name	Type	Description
deco	OBJECT View.GraphDecoration	The instance to be used
visible	BOOL	True if labels should be visible, default value is true.

Sample

View.GraphDecoration.setLabelsVisible(graphDecoration, false)

setPolarPlot()

Short description

Sets whether to use a polar or a linear visualization. If a polar visualization is chosen the coordinates of the graph will be used as angle (in radians) and the value as distance.

Parameters
Name	Type	Description
deco	OBJECT View.GraphDecoration	The instance to be used
polarVisualization	BOOL	True if a polar visualization should be used, default value is false.

Sample

View.GraphDecoration.setPolarPlot(graphDecoration, true)

setTicksVisible()

Short description

Sets whether to show or hide the axes ticks.

Parameters
Name	Type	Description
deco	OBJECT View.GraphDecoration	The instance to be used
visible	BOOL	True if ticks should be visible, default value is true.

Sample

View.GraphDecoration.setTicksVisible(graphDecoration, false)

setTitle()

Short description

Sets the title text.

Parameters
Name	Type	Description
deco	OBJECT View.GraphDecoration	The instance to be used
title	STRING	Title of the graph. Empty by default

Sample

View.GraphDecoration.setTitle(graphDecoration, "Value over Time")

setTitleSize()

Short description

Sets the text size of the graph title.

Parameters
Name	Type	Description
deco	OBJECT View.GraphDecoration	The instance to be used
size	FLOAT	Title size. The default value is 0, which lets the viewer automatically decide the size.

Sample

View.GraphDecoration.setTitleSize(graphDecoration, 3)

setXBounds()

Short description

Sets the graphs dimensions in x direction if lowerBound < upperBound, otherwise the dimension will be adjusted automatically

Parameters
Name	Type	Description
deco	OBJECT View.GraphDecoration	The instance to be used
lowerBound	FLOAT	Lower bound. The default value is 0, which lets the viewer automatically decide the value.
upperBound	FLOAT	Upper bound. The default value is 0, which lets the viewer automatically decide the value.

Sample

View.GraphDecoration.setXBounds(graphDecoration, 0, 250)

setYBounds()

Short description

Sets the graphs dimensions in y direction if lowerBound < upperBound, otherwise the dimension will be adjusted automatically

Parameters
Name	Type	Description
deco	OBJECT View.GraphDecoration	The instance to be used
lowerBound	FLOAT	Lower bound. The default value is 0, which lets the viewer automatically decide the value.
upperBound	FLOAT	Upper bound. The default value is 0, which lets the viewer automatically decide the value.

Sample

View.GraphDecoration.setYBounds(graphDecoration, -250, 250)

toString()

Short description

Gets a user-friendly string description of the graph decoration.

Parameters
Name	Type	Description
deco	CONST_OBJECT View.GraphDecoration	The instance to be used

Return values
Name	Type	Description
str	STRING	User-friendly description of the graph decoration.

Sample

str = View.GraphDecoration.toString(graphDecoration)

View.ImageDecoration

Short description

Decoration object that describes visualization properties for an image.

Overview

create(), setColormap(), setRange(), toString()

Functions

create()

Short description

Creates a new ImageDecoration. The default values for the decoration are: - range = [0,255] - colorMapID = 0

Return values
Name	Type	Description
imageDecorator	OBJECT View.ImageDecoration	The new ImageDecoration

Sample

imageDecoration = View.ImageDecoration.create()

setColormap()

Short description

Sets an integer ID for the color map to use. An image viewer can have a predefined set of color maps to show scalar images false-coded in color for better contrast.

Parameters
Name	Type	Description
imageDecorator	OBJECT View.ImageDecoration	The instance to be used.
colorMapID	INT	An integer ID for the color map to use. The set of color maps available depends on the viewer component.

Sample

View.ImageDecoration.setColormap(imageDecorator, 2)

setRange()

Short description

Sets the pixel value range to visualize. For example, if the range [100,500] is set, all pixel values below 100 should be mapped to black and all pixel values above 500 should be mapped to white. Please note that this function has no effect for UINT8 and RGB24 images.

Parameters
Name	Type	Description
imageDecorator	OBJECT View.ImageDecoration	The instance to be used.
minRange	FLOAT	The lower bound of the range to visualize.
maxRange	FLOAT	The upper bound of the range to visualize.

Sample

View.ImageDecoration.setRange(imageDecorator, 100, 500)

toString()

Short description

Gets a user-friendly string description of the image decoration.

Parameters
Name	Type	Description
imageDecoration	CONST_OBJECT View.ImageDecoration	The decoration object.

Return values
Name	Type	Description
str	STRING	User-friendly description of the image decoration.

Sample

str = View.ImageDecoration.toString(imageDecoration)

View.MeshDecoration

Short description

Decoration object that describes visualization properties for a mesh.

Overview

create(), setSurfaceColor(), setVisibleFaces(), toString()

Functions

create()

Short description

Create a new MeshDecoration.

Return values
Name	Type	Description
handle	OBJECT View.MeshDecoration	The new MeshDecoration

Sample

handle = View.MeshDecoration.create()

setSurfaceColor()

Short description

Set the color of the surface. This color is assigned to the ambient and diffuse material properties. Note that the alpha channel is currently unsupported and will have no effect.

Parameters
Name	Type	Description
handle	OBJECT View.MeshDecoration	The instance to be used.
r	INT	Red value in range (0,255).
g	INT	Green value in range (0,255).
b	INT	Blue value in range (0,255).
a	INT	Alpha value in range (0,255). Currently unused.

Sample

View.MeshDecoration.setSurfaceColor(handle, 0, 100, 0)

setVisibleFaces()

Short description

Set the triangle face to be rendered.

Parameters
Name	Type	Description
handle	OBJECT View.MeshDecoration	The instance to be used.
visibleFaces	ENUM VisibleFaces	Specifies what face(s) of the triangles to be rendered. By default both faces are rendered.

Sample

View.MeshDecoration.setVisibleFaces(handle, "FRONT_AND_BACK")

toString()

Short description

Get a user-friendly string description of the mesh decoration.

Parameters
Name	Type	Description
handle	CONST_OBJECT View.MeshDecoration	The decoration object.

Return values
Name	Type	Description
str	STRING	User-friendly description of the mesh decoration.

Sample

str = View.MeshDecoration.toString(handle)

View.PixelRegionDecoration

Short description

Decoration object that describes visualization properties for a pixel region.

Overview

create(), setColor(), toString()

Functions

create()

Short description

Creates a new PixelRegionDecoration.

Return values
Name	Type	Description
pixelRegionDecorator	OBJECT View.PixelRegionDecoration	The new PixelRegionDecoration

Sample

pixelRegionDecoration = View.PixelRegionDecoration.create()

setColor()

Short description

Sets the pixel region color.

Parameters
Name	Type	Description
pixelRegionDecorator	OBJECT View.PixelRegionDecoration	The instance to be used.
red	INT	Red value in range [0,255].
green	INT	Green value in range [0,255].
blue	INT	Blue value in range [0,255].
alpha	INT	Optional alpha value in range [0,255].

Sample

View.PixelRegionDecoration.setColor(pixelRegionDecorator, 255, 0, 0, 255)

toString()

Short description

Gets a user-friendly string description of the pixel region decoration.

Parameters
Name	Type	Description
pixelRegionDecoration	CONST_OBJECT View.PixelRegionDecoration	The decoration object.

Return values
Name	Type	Description
str	STRING	User-friendly description of the pixel region decoration.

Sample

str = View.PixelRegionDecoration.toString(pixelRegionDecoration)

View.PointCloudDecoration

Short description

Decoration object that describes visualization properties for a point cloud.

Overview

create(), setIntensityColormap(), setIntensityRange(), setPointSize(), setXColormap(), setXRange(), setYColormap(), setYRange(), setZColormap(), setZRange(), toString()

Functions

create()

Short description

Create a new PointCloudDecoration.

Return values
Name	Type	Description
handle	OBJECT View.PointCloudDecoration	The new PointCloudDecoration

Sample

pointCloudDecoration = View.PointCloudDecoration.create()

setIntensityColormap()

Short description

Set an integer ID for the color map to use for the Intensity range (0 = gray scale).

Parameters
Name	Type	Description
handle	OBJECT View.PointCloudDecoration	The instance to be used.
colorMapID	INT	An integer ID for the color map to use. The set of color maps available depends on the viewer component.

Sample

View.PointCloudDecoration.setIntensityColormap(handle, 2)

setIntensityRange()

Short description

Set the lower and upper bound of this component.

Parameters
Name	Type	Description
handle	OBJECT View.PointCloudDecoration	The instance to be used.
minValue	FLOAT	The lower bound of the intensity range to visualize.
maxValue	FLOAT	The upper bound of the intensity range to visualize.

Sample

View.PointCloudDecoration.setIntensityRange(handle, 0.1, 0.9)

setPointSize()

Short description

Set the size of displayed points.

Parameters
Name	Type	Description
handle	OBJECT View.PointCloudDecoration	The instance to be used.
pointSize	FLOAT	The size of a point

Sample

View.PointCloudDecoration.setPointSize(handle, 2)

setXColormap()

Short description

Set an integer ID for the color map to use for the X range (0 = gray scale).

Parameters
Name	Type	Description
handle	OBJECT View.PointCloudDecoration	The instance to be used.
colorMapID	INT	An integer ID for the color map to use. The set of color maps available depends on the viewer component.

Sample

View.PointCloudDecoration.setXColormap(handle, 2)

setXRange()

Short description

Set the lower and upper bound of this component.

Parameters
Name	Type	Description
handle	OBJECT View.PointCloudDecoration	The instance to be used.
minValue	FLOAT	The lower bound of the x range to visualize.
maxValue	FLOAT	The upper bound of the x range to visualize.

Sample

View.PointCloudDecoration.setXRange(handle, -100, 100)

setYColormap()

Short description

Set an integer ID for the color map to use for the Y range (0 = gray scale).

Parameters
Name	Type	Description
handle	OBJECT View.PointCloudDecoration	The instance to be used.
colorMapID	INT	An integer ID for the color map to use. The set of color maps available depends on the viewer component.

Sample

View.PointCloudDecoration.setYColormap(handle, 2)

setYRange()

Short description

Set the lower and upper bound of this component.

Parameters
Name	Type	Description
handle	OBJECT View.PointCloudDecoration	The instance to be used.
minValue	FLOAT	The lower bound of the y range to visualize.
maxValue	FLOAT	The upper bound of the y range to visualize.

Sample

View.PointCloudDecoration.setYRange(handle, -100, 100)

setZColormap()

Short description

Set an integer ID for the color map to use for the Z range (0 = gray scale).

Parameters
Name	Type	Description
handle	OBJECT View.PointCloudDecoration	The instance to be used.
colorMapID	INT	An integer ID for the color map to use. The set of color maps available depends on the viewer component.

Sample

View.PointCloudDecoration.setZColormap(handle, 2)

setZRange()

Short description

Set the lower and upper bound of this component.

Parameters
Name	Type	Description
handle	OBJECT View.PointCloudDecoration	The instance to be used.
minValue	FLOAT	The lower bound of the z range to visualize.
maxValue	FLOAT	The upper bound of the z range to visualize.

Sample

View.PointCloudDecoration.setZRange(handle, -100, 100)

toString()

Short description

Get a user-friendly string description of the point cloud decoration.

Parameters
Name	Type	Description
handle	CONST_OBJECT View.PointCloudDecoration	The decoration object.

Return values
Name	Type	Description
str	STRING	User-friendly description of the point cloud decoration.

Sample

str = View.PointCloudDecoration.toString(handle)

View.ShapeDecoration

Short description

Decoration object that describes visualization properties for shapes and points.

Overview

create(), setFillColor(), setLineColor(), setLineWidth(), setPointSize(), setPointType(), toString()

Functions

create()

Short description

Creates a new ShapeDecoration. The default values for the decoration are: - lineWidth = 1.0 - lineColor = (0, 0, 0, 255) - fillColor = (0, 0, 0, 0) - pointType = "DOT" - pointSize = 3.0 These values can be changed by using the corresponding functions.

Return values
Name	Type	Description
deco	OBJECT View.ShapeDecoration	The new ShapeDecoration

Sample

shapeDecoration = View.ShapeDecoration.create()

setFillColor()

Short description

Sets the fill color. It will be used to fill shape iconics.

Parameters
Name	Type	Description
deco	OBJECT View.ShapeDecoration	The instance to be used.
red	INT	Red
green	INT	Green
blue	INT	Blue
alpha	INT	Alpha

Sample

View.ShapeDecoration.setFillColor(shapeDecoration, 255, 0, 0, 255)

setLineColor()

Short description

Sets the line color. It will be used for line, points and text iconics as well as stroke color for shape iconics.

Parameters
Name	Type	Description
deco	OBJECT View.ShapeDecoration	The instance to be used.
red	INT	Red
green	INT	Green
blue	INT	Blue
alpha	INT	Alpha

Sample

View.ShapeDecoration.setLineColor(shapeDecoration, 255, 0, 0, 255)

setLineWidth()

Short description

Set the line width.

Parameters
Name	Type	Description
deco	OBJECT View.ShapeDecoration	The instance to be used.
width	FLOAT	Width

Sample

View.ShapeDecoration.setLineWidth(shapeDecoration, 2.3)

setPointSize()

Short description

Sets the point size for point iconics.

Parameters
Name	Type	Description
deco	OBJECT View.ShapeDecoration	The instance to be used.
size	FLOAT	Size

Sample

View.ShapeDecoration.setPointSize(shapeDecoration, 3.5)

setPointType()

Short description

Sets the display type for point iconics.

Parameters
Name	Type	Description
deco	OBJECT View.ShapeDecoration	The instance to be used.
type	ENUM PointType	The point type (DOT or CROSS).

Sample

View.ShapeDecoration.setPointType(shapeDecoration, "CROSS")

toString()

Short description

Gets a user-friendly string description of the shape decoration.

Parameters
Name	Type	Description
shapeDecoration	CONST_OBJECT View.ShapeDecoration	The decoration object.

Return values
Name	Type	Description
str	STRING	User-friendly description of the shape decoration.

Sample

str = View.ShapeDecoration.toString(shapeDecoration)

View.TextDecoration

Short description

Decoration object that describes visualization properties for text overlays. Note that a viewer might not support all properties.

Overview

create(), setBillboardActive(), setBounds(), setColor(), setFontFamily(), setHorizontalAlignment(), setLineSpacing(), setPosition(), setRotation(), setSize(), setVerticalAlignment(), toString()

Functions

create()

Short description

Creates a new TextDecoration.

Return values
Name	Type	Description
textDecorator	OBJECT View.TextDecoration	The new TextDecoration

Sample

textDecorator = View.TextDecoration.create()

setBillboardActive()

Short description

Enable billboard mode. Default is off. When active, the text always faces the camera, and setRotation has no effect.

Parameters
Name	Type	Description
textDecorator	OBJECT View.TextDecoration	The instance to be used.
active	BOOL	Set true to activate billboard.

Sample

View.TextDecoration.setBillboardActive(textDecorator, true)

setBounds()

Short description

Sets the size of the enclosing bounding box. If set, the text is aligned inside these bounds. The box has its origin at position.

Parameters
Name	Type	Description
textDecorator	OBJECT View.TextDecoration	The instance to be used.
width	INT	The bounds width.
height	INT	The bounds height.

Sample

View.TextDecoration.setBounds(textDecorator, 300, 100)

setColor()

Short description

Sets the text color.

Parameters
Name	Type	Description
textDecorator	OBJECT View.TextDecoration	The instance to be used.
red	INT	Red value in range [0,255].
green	INT	Green value in range [0,255].
blue	INT	Blue value in range [0,255].
alpha	INT	Optional alpha value in range [0,255].

Sample

View.TextDecoration.setColor(textDecorator, 255, 0, 0, 255)

setFontFamily()

Short description

Sets the font style family of the text, e.g., sans serif, mono-spaced or serif font style. Depending on the platform the viewer runs on, a concrete font is selected within the given font family.

Parameters
Name	Type	Description
textDecorator	OBJECT View.TextDecoration	The instance to be used.
fontFamily	ENUM FontFamily	Font family (SANSSERIF, MONOSPACE, SERIF). Default is SANSSERIF.

Sample

View.TextDecoration.setFontFamily(textDecorator, "MONOSPACE")

setHorizontalAlignment()

Short description

Sets the horizontal alignment of the text relative to the given text position.

Parameters
Name	Type	Description
textDecorator	OBJECT View.TextDecoration	The instance to be used.
horizontalAlignment	ENUM HorizontalAlignment	Horizontal alignment (LEFT, CENTER, RIGHT). Default is LEFT.

Sample

View.TextDecoration.setHorizontalAlignment(textDecorator, "CENTER")

setLineSpacing()

Short description

Sets the line spacing in % of the text size.

Parameters
Name	Type	Description
textDecorator	OBJECT View.TextDecoration	The instance to be used.
lineSpacing	FLOAT	The line spacing factor. The default value is 1.1.

Sample

View.TextDecoration.setLineSpacing(textDecorator, 1.2)

setPosition()

Short description

Sets the text position.

Parameters
Name	Type	Description
textDecorator	OBJECT View.TextDecoration	The instance to be used.
positionX	FLOAT	The text position x-coordinate.
positionY	FLOAT	The text position y-coordinate.
positionZ	FLOAT	The text position z-coordinate. Optional, only useful if a 3D viewer is used.

Sample

View.TextDecoration.setPosition(textDecorator, 10, 10)

setRotation()

Short description

Sets the text rotation in radians around the given text position and around the given axis.

Parameters
Name	Type	Description
textDecorator	OBJECT View.TextDecoration	The instance to be used.
rotation	FLOAT	Text rotation in radians. The default value is 0.
axis	FLOAT	A 3d vector which describes the rotation axis. Default is {0,0,-1}.

Sample

View.TextDecoration.setRotation(textDecorator, 1.5708, {0,1,0})

setSize()

Short description

Sets the text font size.

Parameters
Name	Type	Description
textDecorator	OBJECT View.TextDecoration	The instance to be used.
fontSize	FLOAT	The text font size. The default value is 10.

Sample

View.TextDecoration.setSize(textDecorator, 10)

setVerticalAlignment()

Short description

Sets the vertical alignment of the text relative to the given text position.

Parameters
Name	Type	Description
textDecorator	OBJECT View.TextDecoration	The instance to be used.
verticalAlignment	ENUM VerticalAlignment	Vertical alignment (BOTTOM, CENTER, TOP). Default is BOTTOM.

Sample

View.TextDecoration.setVerticalAlignment(textDecorator, "CENTER")

toString()

Short description

Gets a human-friendly string description of the text decoration, containing all properties.

Parameters
Name	Type	Description
textDecoration	CONST_OBJECT View.TextDecoration	The decoration object.

Return values
Name	Type	Description
str	STRING	User-friendly description of the text decoration.

Sample

str = View.TextDecoration.toString(textDecoration)

Enumerations

B: Buttons
C: Cipher.Certificate.SigningRequest.Format Cipher.Key.Format Command.Client.AccessMode Command.Client.ByteOrder Command.Client.ProtocolType Connector.DigitalIn.DebounceMode Connector.DigitalIn.SignalLogic Connector.DigitalOut.ActivationMode Connector.DigitalOut.DelayedEvents.MeasurementUnit Connector.DigitalOut.DelayedEvents.StatusCode Connector.DigitalOut.PortOutputMode Connector.DigitalOut.SignalLogic Container.ItemTypes
D: DigitalInPorts DigitalLogic.Gate.Affinity DigitalOutPorts
E: Encoder.DecoderCountMode Encoder.DecoderPhases Encoder.Direction EncoderIncrementSources EthernetInterfaces
F: FTPClient.SecurityProtocol FTPClient.TransferMode FieldBus.CreateMode FieldBus.TransmissionMode File.Archive.ZIP.Compression
I: Image.BorderType Image.Calibration.Correction.CoordinateSystem Image.Calibration.Correction.CorrectionCropMode Image.ColorSpace Image.ConcatenationDirection Image.ContrastDifferenceMode Image.DifferenceMode Image.ExtremaType Image.GaussianFilterType Image.ImageType Image.InpaintMethod Image.InterpolationMethod Image.Matching.BackgroundClutterLevel Image.Matching.EdgeMatcherProcessingUnit Image.Matching.PatternMatcher.EdgeSensitivity Image.Matching.PatternVerifier.EdgeSensitivity Image.Matching.PointMatcher.PoseType Image.Matching.PointMatcher.PoseVariability Image.MetricType Image.MissingDataMethod Image.MorphologicalTransform Image.OCR.Halcon.AutoSegmenter.AutoSegmentationParameters Image.OCR.Halcon.FontClassifier.PreTrainedFonts Image.OCR.Halcon.ManualSegmenter.ManualSegmentationParameters Image.OutputGrid Image.PixelRegion.Filter.FeatureType Image.ProcessingDimension Image.Provider.Camera.V3TConfig2D.ImageTriggerMode Image.Provider.Camera.V3TConfig3D.ImageTriggerDelayUnit Image.Provider.Camera.V3TConfig3D.ImageTriggerMode Image.Provider.Camera.V3TConfig3D.PeakSelectionMode Image.Provider.Camera.V3TConfig3D.ProfileTriggerMode Image.Pyramid.DownsamplingMethod Image.Pyramid.ProcessingUnit Image.ShapeFitter.EdgeSelection IncrementPortConnectors
L: LEDs LUA.math.Constants LUA.utf8.Constants Log.Level
M: MachineLearning.DataSet.LabelType MachineLearning.KMeansClustering.InitMethod MachineLearning.NeuralNet.ActivationFunction MachineLearning.SupportVectorMachine.KernelType Monitor.App.AppStatus MountedDrives
N: NTPClient.TimeSource
O: OPCUA.AccessLevel OPCUA.DataType OPCUA.EventSeverity OPCUA.NodeClass OPCUA.NodeIDType OPCUA.NodeType OPCUA.ReferenceType OPCUA.Server.SecurityConfiguration.MessageSecurityMode OPCUA.Server.SecurityConfiguration.SecurityPolicy OPCUA.Server.SecurityConfiguration.UserTokenPolicy OPCUA.Server.Value.OptionalFieldState OPCUA.Server.Value.UnionField Object.DataFormat
P: Point.NormType PointCloud.ColorMode PointCloud.Matching.Halcon.SurfaceMatcher.NormalComputationMethod PointCloud.toImageMode Profile.AggregateOperation Profile.ContrastDifferenceMode Profile.CoordinateType Profile.Curve.CurveType Profile.CurveFitter.CurveFitMode Profile.CurveFitter.CurveOutlierMarginType Profile.DifferenceMode Profile.DifferentiationOrder Profile.EdgeSide Profile.ExtremaType Profile.FillInvalidMethod Profile.ImageType Profile.Matching.PatternMatcher.ComparisonMode Profile.NoiseType Profile.SlopePolarity Profile.SortKey
S: Script.Priority Script.Queue.Priority SerialComTypes SerialPorts Shape.OutlierMarginType Shape.PointFitMode Shape.ShapeType Shape3D.Shape3DType Shape3D.ShapePointFitMode Statistics.HistogramCompareMethod
T: Transform.RotationOrder Transform.TransformType TriSpector.DeviceVariant
V: View.Channel View.ColorMap.ColorMapType View.ColorMap.PredefinedColorMap View.GraphDecoration.AspectRatio View.GraphDecoration.GraphType View.MeshDecoration.VisibleFaces View.PointerActionType View.PointerType View.Present.Add.IconicType View.Present.Editor.EditorType View.Present.LogLevel View.ShapeDecoration.PointType View.TextDecoration.FontFamily View.TextDecoration.HorizontalAlignment View.TextDecoration.VerticalAlignment

Buttons

Cipher.Certificate.SigningRequest.Format

Items
Value	Name	Description
PEM		PKCS#10 PEM format

Cipher.Key.Format

Items
Value	Name	Description
PEM		PEM format. PKI X.509 PEM format for public key, PKCS#8 PEM format for private key.

Command.Client.AccessMode

Items
Value	Name	Description
BY_NAME	By name (Default)
BY_INDEX	By index

Command.Client.ByteOrder

Items
Value	Name	Description
BIG_ENDIAN	Big-endian (Default)
LITTLE_ENDIAN	Little-endian

Command.Client.ProtocolType

Items
Value	Name	Description
COLA_A	CoLa A (Default)
COLA_B	CoLa B
COLA_2	CoLa 2

Connector.DigitalIn.DebounceMode

Items
Value	Name	Description
TIME_MS	Time in ms	Time based with milliseconds value
INCREMENT_TICK	Increment in ticks	Increment based with ticks as value

Connector.DigitalIn.SignalLogic

Items
Value	Name	Description
ACTIVE_HIGH	Active high	Active high signal logic is used
ACTIVE_LOW	Active low	Active low signal logic is used

Connector.DigitalOut.ActivationMode

Items
Value	Name	Description
TIME_MS	Time in ms	Time based with milliseconds value
INCREMENT_TICK	Increment in ticks	Increment based with ticks as value

Connector.DigitalOut.DelayedEvents.MeasurementUnit

Items
Value	Name	Description
INCREMENT_TICK	Increment in ticks	Value in encoder ticks
TIME_US	Time in us	Value in microseconds

Connector.DigitalOut.DelayedEvents.StatusCode

Items
Value	Name	Description
OK	OK	The function executed correctly
QUEUE_NOT_ENABLED	Queue not enabled	You have to run Connector.DigitalOut.DelayedEvents.enable before adding a new event
QUEUE_FULL	Queue full	The queue is full
LATE_EVENT	Late event	The added event has already passed
UNORDERED_QUEUE	Unordered queue	The added event does not occur after the last event in the queue
ILLEGAL_DURATION	Illegal duration	Illegal duration value specified

Connector.DigitalOut.PortOutputMode

Items
Value	Name	Description
HIGH_SIDE	High-side	Digital port works as high-side (PNP) output
LOW_SIDE	Low-side	Digital port works as low-side (NPN) output
PUSH_PULL	Push-pull	Digital port works as push-pull output

Connector.DigitalOut.SignalLogic

Items
Value	Name	Description
ACTIVE_HIGH	Active high	Active high signal logic is used
ACTIVE_LOW	Active low	Active low signal logic is used

Container.ItemTypes

The different types of which one item in the container can be. Matches the existing framework types.

Items
Value	Name	Description
OBJECT	object	Only non-const object
CONST_OBJECT	const object	Matches also non-const objects
FLOAT	float
INT	integer
BOOL	bool
STRING	string
BINARY	binary

DigitalInPorts

Items
Value	Name	Description
DI1	Digital In 1
DI2	Digital In 2
DI3	Digital In 3
DI4	Digital Input 4	Programmable IO 4
DI5	Digital Input 5	Programmable IO 5
DI6	Digital Input 6	Programmable IO 6
DI7	Digital Input 7	Programmable IO 7

DigitalLogic.Gate.Affinity

Items
Value	Name	Description
SW	Bound to software
HW	Bound to hardware

DigitalOutPorts

Items
Value	Name	Description
DO4	Digital Output 4	Programmable IO 4
DO5	Digital Output 5	Programmable IO 5
DO6	Digital Output 6	Programmable IO 6
DO7	Digital Output 7	Programmable IO 7

Encoder.DecoderCountMode

Items
Value	Name	Description
BIDIRECTIONAL	Bidirectional	Counts up in Encoder forward / backward direction
POSITIVE_MOVEMENT	Positive Movement	Counts up in Encoder forward direction / counts down in Encoder backward direction
NEGATIVE_MOVEMENT	Negative Movement	Counts down in Encoder forward direction / counts up in Encoder backward direction
FORWARD_MOVEMENT	Forward Movement	Counts up in Encoder forward direction / no count in Encoder backward direction
BACKWARD_MOVEMENT	Backward Movement	No count in Encoder forward direction / counts up in Encoder backward direction

Encoder.DecoderPhases

Items
Value	Name	Description
SINGLE_PHASE	Single Phase
DUAL_PHASE	Dual Phase

Encoder.Direction

Items
Value	Name	Description
FORWARD	Forward Direction
BACKWARD	Backward Direction

EncoderIncrementSources

Items
Value	Name	Description
ENC1	ENC1

EthernetInterfaces

Items
Value	Name	Description
ETH1	Ethernet	The only available ethernet interface.

FTPClient.SecurityProtocol

Items
Value	Name	Description
NONE	None	Plain FTP (no transport security)
FTPS_EXPLICIT	FTPS explicit mode	Require explicit FTP over TLS. Explicit mode: A plain FTP connection is established first, the client then requests to switch to TLS using the FTP command AUTH. This is the usual way to run FTPS.
FTPS_IMPLICIT	FTPS implicit mode	Require implicit FTP over TLS. Implicit mode: A TLS session is established directly, without a previous negotiation via plain FTP. This is a more rare way to run FTPS.

FTPClient.TransferMode

Items
Value	Name	Description
ASCII	ASCII mode
BINARY	Binary mode

FieldBus.CreateMode

Items
Value	Name	Description
EXPLICIT_OPEN	Explicit Open	Only create the handle, but do not automatically open communication. Communication must be started explicitly using the function open.
AUTOMATIC_OPEN	Automatic Open	Create the handle and automatically open the communication

FieldBus.TransmissionMode

Items
Value	Name	Description
CONFIRMED_MESSAGING	Confirmed Messaging	Transmission mode using the SICK Confirmed Messaging protocol to transfer and fragment process data
RAW	Raw	Transmission mode without any protocol

File.Archive.ZIP.Compression

Items
Value	Name	Description
STORE	Store only, no compression
FAST	Fastest compression
DEFAULT	Default compression
BEST	Best compression, slowest

Image.BorderType

Items
Value	Name	Description
CONSTANT	CONSTANT	Example: iiii abcdef iiii
REPLICATE	REPLICATE	Example: aaaa abcdef ffff
REFLECT	REFLECT	Example: dcba abcdef fedc
WRAP	WRAP	Example: cdef abcdef abcd

Image.Calibration.Correction.CoordinateSystem

Items
Value	Name	Description
CAMERA_PIXEL	camera_pixel	Pixel coordinates of the input camera image.
CORRECTED_PIXEL	corrected_pixel	Pixel coordinates of the corrected output image.
CORRECTED_WORLD	corrected_world	Image world coordinates of the corrected output image.
EXTERNAL_WORLD	external_world	Point on the world ground plane (at z=0) as defined by the camera model, usually from a calibration pattern.

Image.Calibration.Correction.CorrectionCropMode

Items
Value	Name	Description
FULL	full	Full mode, creates an output containing all valid pixels and some zero-valued pixels where the corrected image is undefined.
VALID	valid	Valid mode, creates an output containing only valid pixels, cropping out some values to create a rectangular output image.

Image.ColorSpace

Items
Value	Name	Description
COLORSPACE_RGB	RGB	RGB color space
COLORSPACE_HSV	HSV	HSV color space
COLORSPACE_LAB	LAB	LAB color space

Image.ConcatenationDirection

Items
Value	Name	Description
ABOVE	ABOVE	Concatenate image2 above image1
BELOW	BELOW	Concatenate image2 below image1
LEFT	LEFT	Concatenate image2 to the left of image1
RIGHT	RIGHT	Concatenate image2 to the right of image1

Image.ContrastDifferenceMode

Items
Value	Name	Description
ONE	one	At least one point in the neighborhood should have the specified value margin to the extremal point.

Image.DifferenceMode

Items
Value	Name	Description
ABS	ABS	Absolute difference.
SQUARE	SQUARE	Squared difference.

Image.ExtremaType

Items
Value	Name	Description
MAX	MAX	Local maxima
MIN	MIN	Local minima

Image.GaussianFilterType

Items
Value	Name	Description
SIZE_SELECT	SIZE_SELECT	Choose implementation depending on filter size, default.
TRUNCATED	TRUNCATED	Use convolution with a truncated kernel, this is faster for small filter sizes.
RECURSIVE	RECURSIVE	Use a recursive filter to approximate the kernel. The run-time is independent of filter size and is recommended for large filter sizes.

Image.ImageType

Items
Value	Name	Description
INT8	int8	signed 8-bit integer
INT16	int16	signed 16-bit integer
INT32	int32	signed 32-bit integer
INT64	int64	signed 64-bit integer
UINT8	uint8	unsigned 8-bit integer
UINT16	uint16	unsigned 16-bit integer
UINT32	uint32	unsigned 32-bit integer
UINT64	uint64	unsigned 64-bit integer
FLOAT32	float32	32-bit floating-point
FLOAT64	float64	64-bit floating-point
RGB24	RGB24	24-bit RGB color image (stored in BGR byte order)

Image.InpaintMethod

Items
Value	Name	Description
NAVIER_STOKES	NAVIER-STOKES	Navier-Stokes equations based inpainting method.
ALEXANDRU_TELEA	ALEXANDRU TELEA	An Image Inpainting Technique Based on the Fast Marching Method.

Image.InterpolationMethod

Items
Value	Name	Description
NEAREST	nearest	Resample using a nearest-neighbor interpolation
LINEAR	linear	Resample using 2x2 bilinear interpolation

Image.Matching.BackgroundClutterLevel

Items
Value	Name	Description
LOW	low	Very few edges not belonging to the object.
MEDIUM	medium	Some edges in the background not belonging to the object.
HIGH	high	Many edges in the background not belonging to the object.

Image.Matching.EdgeMatcherProcessingUnit

Items
Value	Name	Description
CPU	CPU	Calculations will be done on the CPU.
FPGA	FPGA	The FPGA will be used for hardware acceleration.

Image.Matching.PatternMatcher.EdgeSensitivity

Items
Value	Name	Description
HIGH	High	All pixels contribute to the verification.
LOW	Low	Pixels close to edges are excluded.

Image.Matching.PatternVerifier.EdgeSensitivity

Items
Value	Name	Description
HIGH	High	All pixels contribute to the verification.
LOW	Low	Pixels close to edges are excluded.

Image.Matching.PointMatcher.PoseType

Items
Value	Name	Description
RIGID	Rigid	Searches for objects whose image appears translated and rotated. The scale range is ignored in this mode.
SIMILARITY	Similarity	Searches for objects whose image appears translated, rotated and uniformly scaled.
AFFINE	Affine	Searches for objects whose image appears translated, rotated, non-uniformly scaled and skewed.
HOMOGRAPHY	Homography	This is the most general transform, it allows e.g. out-of-plane rotation for flat objects.

Image.Matching.PointMatcher.PoseVariability

Items
Value	Name	Description
HIGH	HIGH	High pose variability: larger scale changes and visible perspective effects.
LOW	LOW	Low pose variability: scale changes up to 30% and only small perspective effects.

Image.MetricType

Items
Value	Name	Description
ABS	ABS	Compute as L1 norm
MAGNITUDE	MAGNITUDE	Compute as L2 norm

Image.MissingDataMethod

Items
Value	Name	Description
MAX	MAX	Setting missing data pixels to the maximum valid value in the neighborhood.
MIN	MIN	Setting missing data pixels to the minimum valid value in the neighborhood.
MEAN	MEAN	Setting missing data pixels to the mean of all valid values in the neighborhood.
MEDIAN	MEDIAN	Setting missing data pixels to the median of all valid values in the neighborhood.
EDGE	EDGE	Removing missing data by interpolating neighbor pixels in an edge-preserving way.

Image.MorphologicalTransform

Items
Value	Name	Description
ERODE	ERODE	Morphological erosion.
DILATE	DILATE	Morphological dilation.
OPEN	OPEN	Morphological opening
CLOSE	CLOSE	Morphological closure
GRADIENT	GRADIENT	Morphological gradient
TOPHAT	TOPHAT	Morphological tophat
BLACKHAT	BLACKHAT	Morphological blackhat

Image.OCR.Halcon.AutoSegmenter.AutoSegmentationParameters

Items
Value	Name	Description
MIN_CONTRAST	min_contrast	The minimal contrast the characters have to their surrounding background.List of values: integer or float value between 1 and 255 for byte images and between 1 and 65.535 for uint2 images. Default value: 15
POLARITY	polarity	'dark_on_light' if the text to be segmented is darker than its background, 'light_on_dark' if the text to be segmented is lighter than its background, and 'both' if both kinds of text are to be segmented. List of values: 'dark_on_light', 'light_on_dark' or 'both'. Default value: 'both'
MIN_CHAR_HEIGHT	min_char_height	The minimal height of the characters in pixels. If text of arbitrary height is to be segmented, 'auto' may be passed. Note that 'min_char_height' refers to characters only. The height of punctuation marks or separators is not restricted by 'min_char_height'.List of values: integer or float value greater than or equal to 1. Default value: 'auto'
MAX_CHAR_HEIGHT	max_char_height	The maximal height of the characters in pixels. If text of arbitrary height is to be segmented, 'auto' may be passed. Note that 'max_char_height' refers to characters only. The height of punctuation marks or separators is not restricted by 'max_char_height'.List of values: integer or float value greater than or equal to 1. Default value: 'auto'
MIN_CHAR_WIDTH	min_char_width	The minimal width of the characters in pixels. If text of arbitrary width is to be segmented, 'auto' may be passed. Note that 'min_char_width' refers to characters only. The width of punctuation marks or separators is not restricted by 'min_char_width'.List of values: integer or float value greater than or equal to 1. Default value: 'auto'
MAX_CHAR_WIDTH	max_char_width	The maximal width of the characters in pixels. If text of arbitrary width is to be segmented, 'auto' may be passed. Note that 'max_char_width' refers to characters only. The width of punctuation marks or separators is not restricted by 'max_char_width'.List of values: integer or float value greater than or equal to 1. Default value: 'auto'
MIN_STROKE_WIDTH	min_stroke_width	The minimal stroke width of the characters in pixels. If the minimal stroke width is to be estimated within the text segmentation process automatically, 'auto' may be passed. Note that 'min_stroke_width' refers to characters only. The stroke width of punctuation marks or separators is not restricted by 'min_stroke_width'.List of values: integer or float value greater than or equal to 1. Default value: 'auto'
MAX_STROKE_WIDTH	max_stroke_width	The maximal stroke width of the characters in pixels. If the maximal stroke width is to be estimated within the text segmentation process automatically, 'auto' may be passed. Note that 'max_stroke_width' refers to characters only. The stroke width of punctuation marks or separators is not restricted by 'max_stroke_width'.List of values: integer or float value greater than or equal to 1. Default value: 'auto'
ELIMINATE_BORDER_BLOBS	eliminate_border_blobs	'true' if regions that are touching the border of the image domain should be discarded, otherwise 'false'.List of values: 'true','false'. Default value: 'false'
RETURN_PUNCTUATION	return_punctuation	'true' if small punctuation marks that lie close to the base line of the corresponding text line (e.g. dots or commas) are to be returned. 'false' if no such punctuations should be returned.List of values: 'true','false'. Default value: 'true'
RETURN_SEPARATORS	return_separators	'true' if separators such as a minus or the equality sign should be returned as well. 'false' if no separators should be returned.List of values: 'true','false'. Default value: 'true'
ADD_FRAGMENTS	add_fragments	'true' if fragments, such as the dot on the 'i', should be added to the segmented characters, otherwise 'false'. Be aware, that this can cause noise to be added to the segmented characters.List of values: 'true','false'. Default value: 'true'
TEXT_LINE_STRUCTURE	text_line_structure	To simplify the search for specific structures (e.g. dates or serial numbers) within the segmented text, it is possible to define text line structures. For each text line the distances between the characters are calculated, and based on these distances, the text line is divided into text blocks. Short characters such as '.', '_' and '-' are ignored in this process and treated as spaces. Furthermore, it is possible to define user specific separators which are also ignored. See the description of 'text_line_separators' for details. The text line structure is a string that contains the number of characters for every character block and spaces between these character blocks. For example, if the text to be found is a date with two characters for month, day, and year the structure would be '2 2 2'. If the year may consist of two or four characters, the structure would be '2 2 2-4', indicating that the last character block consists of two to four characters. It is possible to provide up to five structures to match by appending an index to the parameter name, e.g. 'text_line_structure_0', 'text_line_structure_1', etc. If 'text_line_structure' is set to an empty string '', the text to be found may have any structure. Please observe, that every text line structure which is found, is saved as in the text result even if they overlap. If the whole text line containing the text line structure is to be returned instead, it is possible to set 'return_whole_line' accordingly. Default value: ''
TEXT_LINE_SEPARATORS	text_line_separators	A string containing the list of characters which are to be ignored in the process of finding text line structures, see 'text_line_structure' for further details. Please note, user specific separators need to be valid characters within the used OCR classifier. For example, if ':' and '\' are to be ignored, ':\\' should be passed. Please observe, that '\' escapes any special symbol to treat it as a literal, and hence '\\' needs to be passed to use '\' as a separator.List of values: '/', ':', ':\\', '\\/:', etc. Default value: ' '
RETURN_WHOLE_LINE	return_whole_line	'false' if only the segmented text line structures are to be returned as text lines. 'true' if each whole text line containing a text line structure is to be returned in text lines.List of values: 'true','false'. Default value: 'false'
MLP_CLASSIFIER	mlp_classifier	The pre-trained font classifier used within findText for text segmentation. Default value: 'Industrial_Rej.omc'

Image.OCR.Halcon.FontClassifier.PreTrainedFonts

Items
Value	Name	Description
DOCUMENT_0_9A_Z_NOREJ	Document_0-9A-Z_NoRej.omc	Pre-trained font classifier for symbols: 0-9, A-Z
DOCUMENT_0_9A_Z_REJ	Document_0-9A-Z_Rej.omc	Pre-trained font classifier for symbols: 0-9, A-Z
DOCUMENT_0_9_NOREJ	Document_0-9_NoRej.omc	Pre-trained font classifier for symbols: 0-9
DOCUMENT_0_9_REJ	Document_0-9_Rej.omc	Pre-trained font classifier for symbols: 0-9
DOCUMENT_A_ZPLUS_NOREJ	Document_A-Z+_NoRej.omc	Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - = + < > . # $ % & ( ) @ * e £ ¥
DOCUMENT_A_ZPLUS_REJ	Document_A-Z+_Rej.omc	Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - = + < > . # $ % & ( ) @ * e £ ¥
DOCUMENT_NOREJ	Document_NoRej.omc	Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - = + < > . # $ % & ( ) @ * e £ ¥
DOCUMENT_REJ	Document_Rej.omc	Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - = + < > . # $ % & ( ) @ * e £ ¥
DOTPRINT	DotPrint.omc	Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - / . * :
DOTPRINT_0_9PLUS	DotPrint_0-9+.omc	Pre-trained font classifier for symbols: 0-9, special characters. Available special characters: - / . * :
DOTPRINT_0_9PLUS_NOREJ	DotPrint_0-9+_NoRej.omc	Pre-trained font classifier for symbols: 0-9, special characters. Available special characters: - / . * :
DOTPRINT_0_9PLUS_REJ	DotPrint_0-9+_Rej.omc	Pre-trained font classifier for symbols: 0-9, special characters. Available special characters: - / . * :
DOTPRINT_0_9	DotPrint_0-9.omc	Pre-trained font classifier for symbols: 0-9
DOTPRINT_0_9A_Z	DotPrint_0-9A-Z.omc	Pre-trained font classifier for symbols: 0-9, A-Z
DOTPRINT_0_9A_Z_NOREJ	DotPrint_0-9A-Z_NoRej.omc	Pre-trained font classifier for symbols: 0-9, A-Z
DOTPRINT_0_9A_Z_REJ	DotPrint_0-9A-Z_Rej.omc	Pre-trained font classifier for symbols: 0-9, A-Z
DOTPRINT_0_9_NOREJ	DotPrint_0-9_NoRej.omc	Pre-trained font classifier for symbols: 0-9
DOTPRINT_0_9_REJ	DotPrint_0-9_Rej.omc	Pre-trained font classifier for symbols: 0-9
DOTPRINT_A_ZPLUS	DotPrint_A-Z+.omc	Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - / . * :
DOTPRINT_A_ZPLUS_NOREJ	DotPrint_A-Z+_NoRej.omc	Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - / . * :
DOTPRINT_A_ZPLUS_REJ	DotPrint_A-Z+_Rej.omc	Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - / . * :
DOTPRINT_NOREJ	DotPrint_NoRej.omc	Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - / . * :
DOTPRINT_REJ	DotPrint_Rej.omc	Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - / . * :
HANDWRITTEN_0_9	HandWritten_0-9.omc	Pre-trained font classifier for symbols: 0-9
HANDWRITTEN_0_9_NOREJ	HandWritten_0-9_NoRej.omc	Pre-trained font classifier for symbols: 0-9
HANDWRITTEN_0_9_REJ	HandWritten_0-9_Rej.omc	Pre-trained font classifier for symbols: 0-9
INDUSTRIAL_0_9PLUS_NOREJ	Industrial_0-9+_NoRej.omc	Pre-trained font classifier for symbols: 0-9, special characters. Available special characters: - / + . $ % * e £ ¥
INDUSTRIAL_0_9PLUS_REJ	Industrial_0-9+_Rej.omc	Pre-trained font classifier for symbols: 0-9, special characters. Available special characters: - / + . $ % * e £ ¥
INDUSTRIAL_0_9A_Z_NOREJ	Industrial_0-9A-Z_NoRej.omc	Pre-trained font classifier for symbols: 0-9, A-Z
INDUSTRIAL_0_9A_Z_REJ	Industrial_0-9A-Z_Rej.omc	Pre-trained font classifier for symbols: 0-9, A-Z
INDUSTRIAL_0_9_NOREJ	Industrial_0-9_NoRej.omc	Pre-trained font classifier for symbols: 0-9
INDUSTRIAL_0_9_REJ	Industrial_0-9_Rej.omc	Pre-trained font classifier for symbols: 0-9
INDUSTRIAL_A_ZPLUS_NOREJ	Industrial_A-Z+_NoRej.omc	Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - / + . $ % * e £ ¥
INDUSTRIAL_A_ZPLUS_REJ	Industrial_A-Z+_Rej.omc	Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - / + . $ % * e £ ¥
INDUSTRIAL_NOREJ	Industrial_NoRej.omc	Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - / + . $ % * e £ ¥
INDUSTRIAL_REJ	Industrial_Rej.omc	Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - / + . $ % * e £ ¥
MICR	MICR.omc	Pre-trained font classifier.
OCRA	OCRA.omc	Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥
OCRA_0_9	OCRA_0-9.omc	Pre-trained font classifier for symbols: 0-9
OCRA_0_9A_Z	OCRA_0-9A-Z.omc	Pre-trained font classifier for symbols: 0-9, A-Z
OCRA_0_9A_Z_NOREJ	OCRA_0-9A-Z_NoRej.omc	Pre-trained font classifier for symbols: 0-9, A-Z
OCRA_0_9A_Z_REJ	OCRA_0-9A-Z_Rej.omc	Pre-trained font classifier for symbols: 0-9, A-Z
OCRA_0_9_NOREJ	OCRA_0-9_NoRej.omc	Pre-trained font classifier for symbols: 0-9
OCRA_0_9_REJ	OCRA_0-9_Rej.omc	Pre-trained font classifier for symbols: 0-9
OCRA_A_ZPLUS	OCRA_A-Z+.omc	Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥
OCRA_A_ZPLUS_NOREJ	OCRA_A-Z+_NoRej.omc	Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥
OCRA_A_ZPLUS_REJ	OCRA_A-Z+_Rej.omc	Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥
OCRA_NOREJ	OCRA_NoRej.omc	Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥
OCRA_REJ	OCRA_Rej.omc	Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥
OCRB	OCRB.omc	Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥
OCRB_0_9	OCRB_0-9.omc	Pre-trained font classifier for symbols: 0-9
OCRB_0_9A_Z	OCRB_0-9A-Z.omc	Pre-trained font classifier for symbols: 0-9, A-Z
OCRB_0_9A_Z_NOREJ	OCRB_0-9A-Z_NoRej.omc	Pre-trained font classifier for symbols: 0-9, A-Z
OCRB_0_9A_Z_REJ	OCRB_0-9A-Z_Rej.omc	Pre-trained font classifier for symbols: 0-9, A-Z
OCRB_0_9_NOREJ	OCRB_0-9_NoRej.omc	Pre-trained font classifier for symbols: 0-9
OCRB_0_9_REJ	OCRB_0-9_Rej.omc	Pre-trained font classifier for symbols: 0-9
OCRB_A_ZPLUS	OCRB_A-Z+.omc	Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥
OCRB_A_ZPLUS_NOREJ	OCRB_A-Z+_NoRej.omc	Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥
OCRB_A_ZPLUS_REJ	OCRB_A-Z+_Rej.omc	Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥
OCRB_NOREJ	OCRB_NoRej.omc	Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥
OCRB_PASSPORT	OCRB_passport.omc	Pre-trained font classifier for symbols: 0-9, A-Z, + and <
OCRB_PASSPORT_NOREJ	OCRB_passport_NoRej.omc	Pre-trained font classifier for symbols: 0-9, A-Z, + and <
OCRB_PASSPORT_REJ	OCRB_passport_Rej.omc	Pre-trained font classifier for symbols: 0-9, A-Z, + and <
OCRB_REJ	OCRB_Rej.omc	Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥
PHARMA	Pharma.omc	Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - / . ( ) :
PHARMA_0_9PLUS	Pharma_0-9+.omc	Pre-trained font classifier for symbols: 0-9, special characters. Available special characters: - / . ( ) :
PHARMA_0_9PLUS_NOREJ	Pharma_0-9+_NoRej.omc	Pre-trained font classifier for symbols: 0-9, special characters. Available special characters: - / . ( ) :
PHARMA_0_9PLUS_REJ	Pharma_0-9+_Rej.omc	Pre-trained font classifier for symbols: 0-9, special characters. Available special characters: - / . ( ) :
PHARMA_0_9	Pharma_0-9.omc	Pre-trained font classifier for symbols: 0-9
PHARMA_0_9A_Z	Pharma_0-9A-Z.omc	Pre-trained font classifier for symbols: 0-9, A-Z
PHARMA_0_9A_Z_NOREJ	Pharma_0-9A-Z_NoRej.omc	Pre-trained font classifier for symbols: 0-9, A-Z
PHARMA_0_9A_Z_REJ	Pharma_0-9A-Z_Rej.omc	Pre-trained font classifier for symbols: 0-9, A-Z
PHARMA_0_9_NOREJ	Pharma_0-9_NoRej.omc	Pre-trained font classifier for symbols: 0-9
PHARMA_0_9_REJ	Pharma_0-9_Rej.omc	Pre-trained font classifier for symbols: 0-9
PHARMA_NOREJ	Pharma_NoRej.omc	Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - / . ( ) :
PHARMA_REJ	Pharma_Rej.omc	Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - / . ( ) :
SEMI	SEMI.omc	Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - .
SEMI_NOREJ	SEMI_NoRej.omc	Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - .
SEMI_REJ	SEMI_Rej.omc	Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - .
UNIVERSAL_0_9_NOREJ	Universal_0-9_NoRej.occ	Pre-trained font classifier for symbols: 0-9
UNIVERSAL_0_9_REJ	Universal_0-9_Rej.occ	Pre-trained font classifier for symbols: 0-9
UNIVERSAL_0_9PLUS_NOREJ	Universal_0-9+_NoRej.occ	Pre-trained font classifier for symbols: 0-9, special characters. Available special characters: - / = + : < > . # $ % & ( ) @ * e £ ¥
UNIVERSAL_0_9PLUS_REJ	Universal_0-9+_Rej.occ	Pre-trained font classifier for symbols: 0-9, special characters. Available special characters: - / = + : < > . # $ % & ( ) @ * e £ ¥
UNIVERSAL_0_9A_Z_NOREJ	Universal_0-9A-Z_NoRej.occ	Pre-trained font classifier for symbols: 0-9, A-Z
UNIVERSAL_0_9A_Z_REJ	Universal_0-9A-Z_Rej.occ	Pre-trained font classifier for symbols: 0-9, A-Z
UNIVERSAL_0_9A_ZPLUS_NOREJ	Universal_0-9A-Z+_NoRej.occ	Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - / = + : < > . # $ % & ( ) @ * e £ ¥
UNIVERSAL_0_9A_ZPLUS_REJ	Universal_0-9A-Z+_Rej.occ	Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - / = + : < > . # $ % & ( ) @ * e £ ¥
UNIVERSAL_A_ZPLUS_NOREJ	Universal_A-Z+_NoRej.occ	Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - / = + : < > . # $ % & ( ) @ * e £ ¥
UNIVERSAL_A_ZPLUS_REJ	Universal_A-Z+_Rej.occ	Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - / = + : < > . # $ % & ( ) @ * e £ ¥
UNIVERSAL_NOREJ	Universal_NoRej.occ	Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - / = + : < > . # $ % & ( ) @ * e £ ¥
UNIVERSAL_REJ	Universal_Rej.occ	Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - / = + : < > . # $ % & ( ) @ * e £ ¥

Image.OCR.Halcon.ManualSegmenter.ManualSegmentationParameters

Items
Value	Name	Description
CHAR_HEIGHT	char_height	Height of the characters in pixels. Refers to an uppercase character. List of values: integer or float value greater than or equal to 1. Default value: 30px
CHAR_WIDTH	char_width	Width of the characters in pixels. Refers to an uppercase character. List of values: integer or float value greater than or equal to 1. Default value: 20px
STROKE_WIDTH	stroke_width	Stroke width of the characters in pixels. List of values: integer or float value greater than or equal to 0. Default value: 4.0px
BASE_LINE_TOLERANCE	base_line_tolerance	Maximum base line deviation of the characters (in percent of 'char_height'). Default value: 0.15
POLARITY	polarity	'dark_on_light' if the text to be segmented is darker than its background, otherwise 'light_on_dark'. List of values: 'dark_on_light' or 'light_on_dark'. Default value: 'dark_on_light'
UPPERCASE_ONLY	uppercase_only	'true' if the text to be segmented contains uppercase characters or numbers only, otherwise 'false'. Default value: 'false'
IS_DOTPRINT	is_dotprint	'true' if the text to be segmented is a dotprint, otherwise 'false'. Default value: 'false'
IS_IMPRINTED	is_imprinted	'true' if the text to be segmented suffers of local changes of polarity due to reflections, otherwise 'false'. Default value: 'false'
ELIMINATE_HORIZONTAL_LINES	eliminate_horizontal_lines	'true' if there are longer horizontal structures close to the text to be segmented, otherwise 'false'. Default value: 'false'
ELIMINATE_BORDER_BLOBS	eliminate_border_blobs	'true' if regions that are touching the border of the image domain should be discarded, otherwise 'false'. Default value: 'false'
MAX_LINE_NUM	max_line_num	Maximum number of lines to be found. Zero or negative values indicate no limitation. Setting 'max_line_num' to a low value may strongly improve the runtime of findText. Default value: no limitation
RETURN_PUNCTUATION	return_punctuation	'true' if punctuation marks (e.g., dots or comma) should be added to the segmented characters. Default value: 'true'
RETURN_SEPARATORS	return_separators	'true' if separators such as a minus or the equality sign should be added to the segmented characters. Default value: 'true'
ADD_FRAGMENTS	add_fragments	'true' if fragments, such as the dot on the 'i', should be added to the segmented characters. Be aware, that this can cause noise to be added to the segmented characters. Default value: 'true'
FRAGMENT_SIZE_MIN	fragment_size_min	minimum area of fragment regions that are added if 'add_fragments' is set to 'true'. List of values: integer value greater than or equal to 0. Default value: 1
TEXT_LINE_STRUCTURE	text_line_structure	To simplify the search for specific structures (e.g. dates or serial numbers) within the segmented text, it is possible to define text line structures. For each text line the distances between the characters are calculated, and based on these distances, the text line is divided into text blocks. Short characters such as '.', '_' and '-' are ignored in this process and treated as spaces. The text line structure is a string that contains the number of characters for every character block and spaces between these character blocks. For example, if the text to be found is a date with two characters for month, day, and year the structure would be '2 2 2'. If the year may consist of two or four characters, the structure would be '2 2 2-4', indicating that the last character block consists of two to four characters. It is possible to provide up to five structures to match by appending an index to the parameter name, e.g. 'text_line_structure_0', 'text_line_structure_1', etc. If 'text_line_structure' is set to an empty string '', the text to be found may have any structure. Please observe, that every text line structure which is found, is saved as in the text result even if they overlap. Default value: ''

Image.OutputGrid

Items
Value	Name	Description
SAME	SAME	The output is painted on the same pixel grid as the input.
FULL	FULL	The origin and size of the output image is adjusted to fit the entire output. The world pixel size of the input image is used.

Image.PixelRegion.Filter.FeatureType

Items
Value	Name	Description
CENTROIDX	centroid x	Center of gravity in world coordinates, x part. See getCenterOfGravity.
CENTROIDY	centroid y	Center of gravity in world coordinates, y part. See getCenterOfGravity.
PIXELCOUNT	pixel count	Number of region pixels. See countPixels
AREA	area	Region area in world units. See getArea.
VOLUME	volume	Volume in world units. See getVolume.
PERIMETER	perimiter	Region perimeter in world units. See getPerimeterLength.
LARGESTSIDE	largest side	Largest side of a minimum area rectangle in world units (min-area rectangle fitted with accuracy 0.1 degrees). See getBoundingBoxOriented.
SMALLESTSIDE	smallest side	Smallest side of a minimum area rectangle in world units (min-area rectangle fitted with accuracy 0.1 degrees). See getBoundingBoxOriented.
MAJORAXIS	major axis	Length of major principal axis in world units. See getPrincipalAxes.
MINORAXIS	minor axis	Length of minor principal axis in world units. See getPrincipalAxes.
ROTATION	rotation	Rotation of major principal axis in world units. See getPrincipalAxes.
ELONGATION	elongation	Ratio of major / minor axis lengths. See getElongation.
CONVEXITY	convexity	Ratio of area / convex hull area. See getConvexity.
COMPACTNESS	compactness	Compactness measure (4PIAREA) / PERIMETER^2. See getCompactness.
HOLESCOUNT	holes count	Number of holes. See countHoles.
TOUCHESBORDER	touches border	Touches border status (1 if region touches image border, 0 otherwise). See touchesImageBorder.
AVERAGEVALUE	average value	Average image intensity or height map value within the region. See getStatistics.
MINVALUE	min value	Minimum image intensity or height map value within the region. See getStatistics.
MAXVALUE	max value	Maximum image intensity or height map value within the region. See getStatistics.
STDDEVVALUE	std value	Standard deviation of image intensity or height map value within the region. See getStatistics.
MEDIANVALUE	median value	Median of image intensity or height map value within the region. See getMedian.
PERC10VALUE	percentile 10 value	10%-level (rank measure) of image intensity or height map value within the region (10% of all values are lower than this value). See getPercentiles.
PERC90VALUE	percentile 90 value	90%-level (rank measure) of image intensity or height map value within the region (90% of all values are lower than this value). See getPercentiles.

Image.ProcessingDimension

Items
Value	Name	Description
ROW	ROW	Do processing row-wise
COLUMN	COLUMN	Do processing column-wise

Image.Provider.Camera.V3TConfig2D.ImageTriggerMode

Items
Value	Name	Description
NONE	None (Continous)	Image acquisition is running continously
SOFTWARE	Software	Image acquistion is triggered by software call

Image.Provider.Camera.V3TConfig3D.ImageTriggerDelayUnit

Items
Value	Name	Description
MS	ms (milliseconds)	Delay is specified in milliseconds
MM	mm (millimeters)	Delay is specified in millimeters

Image.Provider.Camera.V3TConfig3D.ImageTriggerMode

Items
Value	Name	Description
NONE	None (Continous)	Image acquisition is running continously
OBJECT	Object	Image acquisition is triggered by objects higher than the threshold determined by setObjectTriggerLine
IO_3	I/O 3	Image acquisition is triggered by I/O 3 signal
SOFTWARE	Software	Image acquistion is triggered by Image.Provider.Camera.trigger()

Image.Provider.Camera.V3TConfig3D.PeakSelectionMode

Items
Value	Name	Description
STRONGEST	Strongest	Use the point with the strongest intensity in each column as the laser peak
TOP_MOST	Top most	Use the top most point with intensity greater than the configured laser threshold in each column as the laser peak
BOTTOM_MOST	Bottom most	Use the bottom most point with intensity greater than the configured laser threshold when detecting the laser peak

Image.Provider.Camera.V3TConfig3D.ProfileTriggerMode

Items
Value	Name	Description
FREE_RUNNING	Free running	Acquire images at a constant speed, not using an encoder
ENCODER	Encoder	Use a connected encoder to be able to handle variations in speed during image acquisition

Image.Pyramid.DownsamplingMethod

Items
Value	Name	Description
NEAREST	nearest	Downsample using nearest neighbor.
LINEAR	linear	Downsample using 2x2 linear interpolation.
GAUSSIAN	gaussian	Downsample using a Gaussian interpolation.

Image.Pyramid.ProcessingUnit

Items
Value	Name	Description
CPU	CPU	Calculations will be done on the CPU.
FPGA	FPGA	The FPGA will be used for hardware acceleration.

Image.ShapeFitter.EdgeSelection

Items
Value	Name	Description
STRONGEST	strongest	Strongest edge found
FIRST	first	First edge found
LAST	last	Last edge found

IncrementPortConnectors

Items
Value	Name	Description
INC1	INC1

LEDs

Items
Value	Name	Description
STATE_LED	LED State	Supported Colors: green
RESULT_LED	LED Result	Supported Colors: red, green, blue

LUA.math.Constants

Items
Value	Name	Description
math.huge	huge	The value HUGE_VAL, a value larger than or equal to any other numerical value.
math.pi	pi	The value of Pi (3.1415….).

LUA.utf8.Constants

Items
Value	Name	Description
utf8.charpattern	UTF8 Pattern	The pattern (a string, not a function) '[\0-\x7F\xC2-\xF4][\x80-\xBF]*' (see 6.4.1), which matches exactly one UTF-8 byte sequence, assuming that the subject is a valid UTF-8 string.

Log.Level

Items
Value	Name	Description
OFF	Log nothing
SEVERE	Log only severe errors
WARNING	Log warnings and severe errors
INFO	Log infos, warnings and severe errors
FINE	Log fine, infos, warnings and severe errors
FINER	Log finer, fine, infos, warnings and severe errors
FINEST	Log finest, finer, fine, infos, warnings and severe errors
ALL	Log all messages

MachineLearning.DataSet.LabelType

Items
Value	Name	Description
CLASSIFICATION	CLASSIFICATION	Specify the use of discrete labels, this is what should be used when trying to separate distinct classes.
REGRESSION	REGRESSION	Specify the use of floating point labels. This is useful when the labels can be sorted or meaningfully compared.

MachineLearning.KMeansClustering.InitMethod

Items
Value	Name	Description
RANDOM	RANDOM	Place start centers for clusters at random
ESTIMATE	ESTIMATE	Try to estimate a good starting position

MachineLearning.NeuralNet.ActivationFunction

Items
Value	Name	Description
IDENTITY	IDENTITY	Identity activation function, eg. f(x) = x.
SIGMOID	SIGMOID	Sigmoid activation function, eg. f(x) ~ tanh(x).
GAUSSIAN	GAUSSIAN	Gaussian activation function, eg. f(x) ~ exp(-x^2).

MachineLearning.SupportVectorMachine.KernelType

Items
Value	Name	Description
LINEAR	LINEAR	Linear kernel. No mapping is done, linear discrimination (or regression) is done in the original feature space. It is the fastest option. K(x, y) = x^T * y.
GAUSSIAN	GAUSSIAN	Radial basis function (RBF), a good choice in most cases. K(x, y) = e^{-
	x -

Monitor.App.AppStatus

The different possible status of an app.

Items
Value	Name	Description
UNKNOWN	UNKNOWN
RUNNING	RUNNING
STOPPED	STOPPED
CRASHED	CRASHED

MountedDrives

Items
Value	Name	Description
/ram	RAM
/sdcard/0	SDCARD

NTPClient.TimeSource

Items
Value	Name	Description
MANUAL	Manual	Don’t update the time over NTP
NTP	NTP	Update the time over NTP

OPCUA.AccessLevel

Possibilities to access a VARIABLE node value

Items
Value	Name	Description
READ	Read	The value is read only
READ_WRITE	ReadWrite	The value can be read and written

OPCUA.DataType

Enumeration of the supported OPC UA built-in data types

Items
Value	Name	Description
BYTE_STRING	ByteString	An array of unsigned bytes
BOOL	Bool	A boolean value
BYTE	Byte	An unsigned byte
SBYTE	SByte	A signed byte
INT16	Int16	A 16 bit signed integer
UINT16	UInt16	A 16 bit unsigned integer
INT32	Int32	A 32 bit signed integer
UINT32	UInt32	A 32 bit unsigned integer
INT64	Int64	A 64 bit signed integer
UINT64	UInt64	A 64 bit unsigned integer
FLOAT	Float	A 32 bit IEEE-754 floating point number
DOUBLE	Double	A 64 bit IEEE-754 floating point number
STRING	String	An UTF-8 String
STATUS_CODE	StatusCode	OPC UA StatusCode (see OPC UA specification part 4 (7.34))
DATE_TIME	DateTime	An instance in time (e.g., 1988-04-30T03:04:05Z; see OPC UA specification part 6 (5.2.2.5))
GUID	Guid	A globally unique identifier encoded as string (e.g., {72962B91-FA75-4AE6-8D28-B404DC7DAF63}, see OPC UA specification part 6 (5.2.2.6))
NODE_ID	NodeId	A node identifier encoded as string (e.g., "i=13" or "ns=12;s=Hello:World"; see OPC UA specification part 6 (5.3.1.10))
EXPANDED_NODE_ID	ExpandedNodeId	An expanded node identifier encoded as string (e.g., "svr=1;ns=2;s=Hello:World" or "svr=1;nsu=http://example.uri.com;s=Hello:World"; see OPC UA specification part 6 (5.3.1.11))
QUALIFIED_NAME	QualifiedName	A qualified name encoded as string of the form ">namespaceindex<:>name<" where namespace index is an unsigned 16 bit integer and name is a string (e.g., "1:some name"; see OPC UA specification part 3 (8.3))
LOCALIZED_TEXT	LocalizedText	A localized text as string of the form ">locale id<:>text<" where locale id is a locale string according to https://www.io.org/standard/57469.html and the actual localized text (e.g., "en-US:Hello World!" or "de:Hallo Welt!"; see OPC UA specification part 3 (8.4 and 8.5))

OPCUA.EventSeverity

Is mapped to OPC UA event severity (0 … 1000)

Items
Value	Name	Description
HIGHEST	Highest	Highest severity (1000)
HIGHER	Higher	Higher severity (900)
HIGH	High	High severity (800)
HIGHER_MEDIUM	HigherMedium	Higher than medium severity (650)
MEDIUM	Medium	Medium severity (500)
LOWER_MEDIUM	LowerMedium	Lower than medium severity (350)
LOW	Low	Low severity (200)
LOWER	Lower	Lower severity (100)
LOWEST	Lowest	Lowest severity (0)

OPCUA.NodeClass

All possible OPC UA node classes

Items
Value	Name	Description
OBJECT	Object	Node representing an object
VARIABLE	Variable	Node representing a (data) variable
METHOD	Method	Node representing a method
OBJECT_TYPE	ObjectType	Node representing an object type
VARIABLE_TYPE	VariableType	Node representing a variable type
REFERENCE_TYPE	ReferenceType	Node representing a reference type
DATA_TYPE	DataType	Node representing a data type
VIEW	View	Node representing a view

OPCUA.NodeIDType

Possible types of OPC UA node ID

Items
Value	Name	Description
NUMERIC	Numeric	An unsigned number is used; value range: 0-4294967295
STRING	String	A string should be used

OPCUA.NodeType

All supported OPC UA standard node types

Items
Value	Name	Description
BASE_DATA_VARIABLE_TYPE	BaseDataVariableType	The variable contains a potentially changeable value that represents data
PROPERTY_TYPE	PropertyType	The variable contains unchangeable data that expresses a property of another node
FOLDER_TYPE	FolderType	The object represents a folder

OPCUA.ReferenceType

Possible types of references from one OPC UA node to another

Items
Value	Name	Description
HAS_COMPONENT	HasComponent	The child node is a part of the parent node
HAS_ORDERED_COMPONENT	HasOrderedComponent	The child node is a part of the parent node; the child nodes are always returned in the same order on discovery
HAS_PROPERTY	HasProperty	The child node describes a property of the parent node, e.g. Input or Output arguments of a method
HAS_SUBTYPE	HasSubtype	The child node is a subtype of the parent node
HAS_EVENT_SOURCE	HasEventSource	The child node causes the parent node to generate an event
HAS_NOTIFIER	HasNotifier	The child node causes the parent node to generate an event, but generates also events itself
ORGANIZES	Organizes	The parent node is a folder which contains the child node
GENERATES_EVENT	GeneratesEvent	The child node describes which event is generated by the parent node (ObjectType, VariableType, Method)
ALWAYS_GENERATES_EVENT	AlwaysGeneratesEvent	The parent node (method) generates this event on each call
HAS_TYPE_DEFINITION	HasTypeDefinition	The definition of the type of the parent node (variable or object)

OPCUA.Server.SecurityConfiguration.MessageSecurityMode

This enum defines all possible message security modes to secure the message exchange between server and client. (cf. OPC UA specification, part 4, 7.15)

Items
Value	Name	Description
NONE	None	Do not sign or encrypt the messages.
SIGN	Sign	Sign the messages.
SIGN_AND_ENCRYPT	SignAndEncrypt	Sign and encrypt the messages.

OPCUA.Server.SecurityConfiguration.SecurityPolicy

This enum defines all security policies that can be used by a client to connect to the server.

Items
Value	Name	Description
NONE	None	Use the http://opcfoundation.org/UA/SecurityPolicy#None security policy, i.e. do not use any security.
BASIC_128_RSA_15	Basic128Rsa15	Use the http://opcfoundation.org/UA/SecurityPolicy#Basic128Rsa15 security policy.
BASIC_256	Basic256	Use the http://opcfoundation.org/UA/SecurityPolicy#Basic256 security policy.
BASIC_256_SHA_256	Basic256Sha256	Use the http://opcfoundation.org/UA/SecurityPolicy#Basic256Sha256 security policy.

OPCUA.Server.SecurityConfiguration.UserTokenPolicy

Defines all possible user token policies / authentication modes that the client can use to establish a connection to the server. (cf. OPC UA specification, part 4, 7.36.1)

Items
Value	Name	Description
ANONYMOUS	Anonymous	Use anonymous authentication.
USERNAME	Username	Use user name and password for authentication.

OPCUA.Server.Value.OptionalFieldState

Items
Value	Name	Description
DISABLED	DISABLED	The field is not present
ENABLED	ENABLED	The field ism present

OPCUA.Server.Value.UnionField

Items
Value	Name	Description
NO_FIELD	NO_FIELD	NO_FIELD
FIELD_1	FIELD_1	FIELD_1
FIELD_2	FIELD_2	FIELD_2
FIELD_3	FIELD_3	FIELD_3
FIELD_4	FIELD_4	FIELD_4
FIELD_5	FIELD_5	FIELD_5
FIELD_6	FIELD_6	FIELD_6
FIELD_7	FIELD_7	FIELD_7
FIELD_8	FIELD_8	FIELD_8
FIELD_9	FIELD_9	FIELD_9
FIELD_10	FIELD_10	FIELD_10
FIELD_11	FIELD_11	FIELD_11
FIELD_12	FIELD_12	FIELD_12
FIELD_13	FIELD_13	FIELD_13
FIELD_14	FIELD_14	FIELD_14
FIELD_15	FIELD_15	FIELD_15
FIELD_16	FIELD_16	FIELD_16
FIELD_17	FIELD_17	FIELD_17
FIELD_18	FIELD_18	FIELD_18
FIELD_19	FIELD_19	FIELD_19
FIELD_20	FIELD_20	FIELD_20
FIELD_21	FIELD_21	FIELD_21
FIELD_22	FIELD_22	FIELD_22
FIELD_23	FIELD_23	FIELD_23
FIELD_24	FIELD_24	FIELD_24
FIELD_25	FIELD_25	FIELD_25
FIELD_26	FIELD_26	FIELD_26
FIELD_27	FIELD_27	FIELD_27
FIELD_28	FIELD_28	FIELD_28
FIELD_29	FIELD_29	FIELD_29
FIELD_30	FIELD_30	FIELD_30
FIELD_31	FIELD_31	FIELD_31
FIELD_32	FIELD_32	FIELD_32

Object.DataFormat

In what kind of format data should be read/written

Items
Value	Name	Description
JSON	JSON
MSGPACK	MessagePack

Point.NormType

Items
Value	Name	Description
L_1_NORM	L-1-Norm	Manhattan distance:
x	+	y
+	z
L_2_NORM	L-2-Norm	Euclidean distance: sqrt(xx+yy+z*z)
L_INFINITY_NORM	L-Infinity-Norm	Maximum of absolute values: max(
x	,	y
,	z	)

PointCloud.ColorMode

Items
Value	Name	Description
INTENSITY	Intensity	Intensity values from 0.0 to 1.0
RGBA	RGBA	Red, Green, Blue, Alpha values from 0 to 255

PointCloud.Matching.Halcon.SurfaceMatcher.NormalComputationMethod

Items
Value	Name	Description
MLS	MLS	Moving least-squares method for more accurate normal estimation.
FAST	Fast	Fast approximate normal estimation method using a small neighborhood.

PointCloud.toImageMode

Items
Value	Name	Description
TOPMOST	topmost	Resolve point ambiguities by picking the upper point, i.e, prioritize points with higher z coordinate.
BOTTOMMOST	bottommost	Resolve point ambiguities by picking the lower point,i.e, prioritize points with a lower z coordinate.

Profile.AggregateOperation

Items
Value	Name	Description
SUM	sum	Sum of values.
MIN	min	Minimal value.
MAX	max	Maximal value.
MEAN	mean	Mean value.
MEDIAN	median	Median value.

Profile.ContrastDifferenceMode

Items
Value	Name	Description
ONE	one	At least one point on each side in the neighborhood should have the specified value margin to the extremal point.
ALL	all	All points in the neighborhood should have the specified value margin to the extremal point.

Profile.CoordinateType

Items
Value	Name	Description
IMPLICIT_1D	implicit_1d	Squared difference.
EXPLICIT_1D	explicit_1d	Squared difference.
IMPLICIT_2D	implicit_2d	Squared difference.
EXPLICIT_2D	explicit_2d	Squared difference.

Profile.Curve.CurveType

Items
Value	Name	Description
POLYNOMIAL	Polynomial	Polynomial function.
EXPONENTIAL	Exponential	Exponential function.
GAUSSIAN	Gaussian	Gaussian function.

Profile.CurveFitter.CurveFitMode

Items
Value	Name	Description
LEAST_SQUARES	least_squares	Ordinary least squares.
RANSAC	ransac	Ransac (random sampling with outlier rejection).

Profile.CurveFitter.CurveOutlierMarginType

Items
Value	Name	Description
RANK	rank	Rank-based margin, defines the rate of points to include. For example, A rank margin of 0.7 means that the best 70% of all points are included and the rest are ignored.
ABSOLUTE	absolute	Absolute outlier margin.

Profile.DifferenceMode

Items
Value	Name	Description
ABS	abs	Absolute difference.
SQUARE	square	Squared difference.

Profile.DifferentiationOrder

Items
Value	Name	Description
FIRST	first	First order
SECOND	second	Second order

Profile.EdgeSide

Items
Value	Name	Description
HIGH	high	Snap to the high side of the slope
LOW	low	Snap to the low side of the slope
CENTER	center	Snap to the slope center (point of maximal derivative)

Profile.ExtremaType

Items
Value	Name	Description
MAX	max	Local maxima
MIN	min	Local minima

Profile.FillInvalidMethod

Items
Value	Name	Description
LINEAR	linear	Squared difference.
NEIGHBOR_MIN	neighbor_min	Squared difference.
NEIGHBOR_MAX	neighbor_max	Squared difference.
NEIGHBOR_MEAN	neighbor_mean	Squared difference.

Profile.ImageType

Items
Value	Name	Description
INT8	int8	signed 8-bit integer
INT16	int16	signed 16-bit integer
INT32	int32	signed 32-bit integer
INT64	int64	signed 64-bit integer
UINT8	uint8	unsigned 8-bit integer
UINT16	uint16	unsigned 16-bit integer
UINT32	uint32	unsigned 32-bit integer
UINT64	uint64	unsigned 64-bit integer
FLOAT32	float32	32-bit floating-point
FLOAT64	float64	64-bit floating-point

Profile.Matching.PatternMatcher.ComparisonMode

Items
Value	Name	Description
XCORRNORM	xCorrNorm	Cross correlation with normalization.
SAD	sad	Sum of absolute difference.

Profile.NoiseType

Items
Value	Name	Description
NORMAL	normal	Normal distribution.
UNIFORM	uniform	Uniform distribution.

Profile.SlopePolarity

Items
Value	Name	Description
POSITIVE	positive	Positive slope (low to high value)
NEGATIVE	negative	Negative slope (high to low value)
ANY	any	Either positive or negative

Profile.SortKey

Items
Value	Name	Description
BY_VALUE	by_value	Sort by value.
BY_COORDINATE	by_coordinate	Sort by coordinate.

Script.Priority

Items
Value	Name	Description
LOW	Low priority
MEDIUM	Medium priority
HIGH	High priority

Script.Queue.Priority

The relative priority for scripts compared to other queues

Items
Value	Name	Description
HIGH	High
MID	Middle (Default)
LOW	Low

SerialComTypes

Items
Value	Name	Description
RS232		Default

SerialPorts

Items
Value	Name	Description
SER1	SER1	This serial interface supports SerialType RS232

Shape.OutlierMarginType

Items
Value	Name	Description
ABSOLUTE	absolute	Absolute outlier margin, defined in world coordinate units (typically mm).
RANK	rank	Rank-based margin, defines the rate of points to include. For example, A rank margin of 0.7 means that the best 70% of all points are included and the rest are ignored.

Shape.PointFitMode

Items
Value	Name	Description
LEASTSQUARES	leastsquares	Ordinary least squares
RANSAC	ransac	Ransac (random sampling with outlier rejection)
ADAPTIVE	adaptive	Ransac with rank-margin. This mode is deprecated and may be removed in a future version. Please use RANSAC and call setOutlierMargin with the margin type set to RANK instead.
TRIMMED	trimmed	Two-stage least squares fitting. The second stage uses only points within the margin around the fitted shape of the first stage.

Shape.ShapeType

Items
Value	Name	Description
LINE	Line	Line shape (infinite length)
LINE_SEGMENT	Line segment	Line segment shape
POLYLINE	Polyline	Polyline shape, open or closed
RECTANGLE	Rectangle	Rectangle shape (possibly rotated)
CIRCLE	Circle	Circle shape
ELLIPSE	Ellipse	Ellipse shape
ARC	Arc	Arc shape, i.e. a part of a circle contour limited by two angles
SECTOR	Sector	Sector shape enclosing a region limited by two angles, an inner and an outer radius

Shape3D.Shape3DType

Items
Value	Name	Description
PLANE	Plane	Plane (with infinite size)
LINE	Line	Line in 3D (infinite length)
LINE_SEGMENT	Line segment	Line segment in 3D
RECTANGLE	Rectangle	2D rectangle in 3D space
CIRCLE	Circle	2D circle in 3D space
ELLIPSE	Ellipse	2D ellipse in 3D space
POLYGON	Polygon	A closed planar 2D polygon in 3D space
BOX	Box	Solid 3D box
CYLINDER	Cylinder	Solid cylinder
ELLIPTIC_CYLINDER	EllipticCylinder	Solid elliptic cylinder (elliptic base area extended with a height)
CONE	Cone	A 3D cone
SPHERE	Sphere	Sphere
POLYLINE	Polyline	An open polyline in 3D

Shape3D.ShapePointFitMode

Items
Value	Name	Description
LEASTSQUARES	leastsquares	Ordinary least squares
RANSAC	ransac	Ransac (random sampling with outlier rejection)
TRIMMED	trimmed	Two-stage least squares fitting. The second stage uses only points within the margin around the fitted shape of the first stage.

Statistics.HistogramCompareMethod

Items
Value	Name	Description
L1	L1 norm	Sum of absolute differences
L2	L2 norm	Euclidean norm, square root of sum of square differences
MAXDIFF	Maximal difference	Maximal difference between corresponding bins (L-infinity norm)
CHI2	Chi-square statistic	Chi-square statistic (normalized sum of squares). This is the default method and should work well in most cases.
KLDIV	Kullback-Leibler divergence	Kullback-Leibler divergence: sum(p[i] * log(p[i] / q[i])

Transform.RotationOrder

Items
Value	Name	Description
XYZ	XYZ	Rotation first around the world x-axis, then the world y-axis and last the world z-axis.
ZYX	ZYX	Rotation first around the world z-axis, then the world y-axis and last the world x-axis.
ZYZ	ZYZ	Rotation first around the world z-axis, then the world y-axis and last the world z-axis.

Transform.TransformType

Items
Value	Name	Description
IDENTITY	Identity	Identity transform
TRANSLATION	Translation	A translation transform shifts an object along the x, y and z axes
RIGID	Rigid	A rigid transform rotates and translates an object
SIMILARITY	Similarity	A similarity transform scales, rotates and translates an object
AFFINE	Affine	An affine transform shears, scales, rotates and translates and object
HOMOGRAPHY	Homography	A homography transform, also known as a projective transform, is the most general linear transform. It includes affine, similarity and rigid transforms as special cases.

TriSpector.DeviceVariant

Items
Value	Name	Description
TriSpectorP 1008	TriSpectorP 1008	TriSpectorP 1008 device variant
TriSpectorP 1030	TriSpectorP 1030	TriSpectorP 1030 device variant
TriSpectorP 1060	TriSpectorP 1060	TriSpectorP 1060 device variant

View.Channel

Items
Value	Name	Description
LIVE	LIVE	In case of queues on the channel, only the latest presented iconics will be delivered. This is the default value for View.present().
ASSURED	ASSURED	None of the presented iconics will be discarded.

View.ColorMap.ColorMapType

Items
Value	Name	Description
LINEAR	LINEAR	Smooth linear transition between color stops
DISCRETE	DISCRETE	Discrete color jumps at the color stops

View.ColorMap.PredefinedColorMap

Items
Value	Name	Description
AUTUMN	AUTUMN	red → yellow
BLUE_WHITE_RED	BLUE_WHITE_RED	blue → white → red
COOL	COOL	aqua → fuchsia
GRAY	GRAY	black → white
HOT	HOT	black → red → yellow → white
HSV	HSV	red → yellow → green → aqua → blue → fuchsia → red
JET	JET	blue → aqua → green → yellow → red
RAINBOW	RAINBOW	red → fuchsia → blue → aqua → green → yellow → red
SPRING	SPRING	fuchsia → yellow
SUMMER	SUMMER	deep sea → lemon
THERMAL	THERMAL	black → pink → orange → yellow → white
TRAFFIC_LIGHT	TRAFFIC_LIGHT	red → yellow → green
WINTER	WINTER	blue → spring green
RGB	RGB	red → green → blue

View.GraphDecoration.AspectRatio

Items
Value	Name	Description
EQUAL	EQUAL	Equal aspect ratio (both axis has the same scaling)
SQUARE	SQUARE	Square aspect ratio
FIT	FIT	Fitting the viewer

View.GraphDecoration.GraphType

Items
Value	Name	Description
DOT	DOT	Dot graph
LINE	LINE	Line graph
BAR	BAR	Bar graph

View.MeshDecoration.VisibleFaces

Items
Value	Name	Description
FRONT	FRONT	Renders the front faces. A front face exists if the triangle vertices, in order, rotate clockwise around the triangle’s center.
BACK	BACK	Renders the back faces. A back face exists if the triangle vertices, in order, rotate counter-clockwise around the triangle’s center.
FRONT_AND_BACK	FRONT_AND_BACK	Renders both front and back faces.
NONE	NONE	Does not render the triangle faces. It can be used for example if only the vertex points are rendered.

View.PointerActionType

Items
Value	Name	Description
CLICKED	CLICKED
DOWN	DOWN
UP	UP

View.PointerType

Items
Value	Name	Description
PRIMARY	PRIMARY
SECONDARY	SECONDARY
MIDDLE	MIDDLE

View.Present.Add.IconicType

Items
Value	Name	Description
HEIGHTMAP	HEIGHTMAP	Add heightmap type
IMAGE	IMAGE	Add image type
PIXEL_REGION	PIXEL_REGION	Add pixel region type
POINT_CLOUD	POINT_CLOUD	Add point cloud type
SHAPE	SHAPE	Add shape type
TEXT	TEXT	Add text type
PROFILE	PROFILE	Add profile type
POLAR_SCAN	POLAR_SCAN	Add polar scan type
MESH	MESH	Add mesh type

View.Present.Editor.EditorType

Items
Value	Name	Description
INSTALL	INSTALL	Install editor
UNINSTALL	UNINSTALL	Uninstall editor

View.Present.LogLevel

Items
Value	Name	Description
INFO	INFO	Log level for info
WARNING	WARNING	Log level for warnings
ERROR	ERROR	Log level for errors

View.ShapeDecoration.PointType

Items
Value	Name	Description
DOT	DOT	a dot to present the point
CROSS	CROSS	a cross to present the point

View.TextDecoration.FontFamily

Items
Value	Name	Description
SANSSERIF	SANSSERIF	Sans Serif font, e.g., Arial, Helvetica style.
MONOSPACE	MONOSPACE	Mono-spaced font, e.g., Courier style.
SERIF	SERIF	Serif font, e.g., Times New Roman style.

View.TextDecoration.HorizontalAlignment

Items
Value	Name	Description
LEFT	LEFT	Align text to the left of the given position.
CENTER	CENTER	Align text centered horizontally relative to given position.
RIGHT	RIGHT	Align text to the right of the given position.
JUSTIFY	JUSTIFY	Align text in a justified mode (stretch spaces to fill the bound’s width).

View.TextDecoration.VerticalAlignment

Items
Value	Name	Description
BOTTOM	BOTTOM	Align bottom of text with the given position.
CENTER	CENTER	Align center of text with the given position.
TOP	TOP	Align top of text with the given position.

Data formats

C: Container
D: DateTime
E: EncoderData
I: Image Image.Calibration.CameraModel Image.Fixture Image.Fixture3D Image.Matching.EdgeMatcher Image.Matching.EdgeMatcher3D Image.Matching.PointMatcher Image.PixelRegion
M: MachineLearning.DataSet Matrix Mesh
P: Parameters.Node Parameters.Node.Array Parameters.Node.Struct Parameters.Node.Variant Point Point2D Point3D Point3D_32 PointCloud PointCloud.XYZI Profile Profile.Curve Profile.Curve.Exponential Profile.Curve.Gaussian Profile.Curve.Polynomial Profile.Log
S: SensorData Shape Shape.Arc Shape.Circle Shape.Composite Shape.Ellipse Shape.Line Shape.LineSegment Shape.PolyLine Shape.Rectangle Shape.Sector Shape3D Shape3D.Box Shape3D.Circle Shape3D.Cone Shape3D.Cylinder Shape3D.Ellipse Shape3D.EllipticCylinder Shape3D.Line Shape3D.LineSegment Shape3D.Plane Shape3D.Polygon Shape3D.Polyline Shape3D.Rectangle Shape3D.Sphere
T: Transform Transform2D Transform3D
V: View.Camera View.ColorMap View.GraphDecoration View.GraphDecoration.ASPECTRATIO View.GraphDecoration.GRAPHTYPE View.GraphDecoration.RGBA View.ImageDecoration View.ImageDecoration.DataRange View.MeshDecoration View.MeshDecoration.VisibleFaces View.PixelRegionDecoration View.PixelRegionDecoration.RGBA View.PointCloudDecoration View.Present.Add View.Present.Clear View.Present.Editor View.Present.Remove View.Present.UpdateDecoration View.Present.UpdateTransform View.ShapeDecoration View.ShapeDecoration.Pixel.RGBA View.ShapeDecoration.PointType View.TextDecoration View.TextDecoration.Bounds View.TextDecoration.FontFamily View.TextDecoration.FontWeight View.TextDecoration.HorizontalAlignment View.TextDecoration.RGBA View.TextDecoration.VerticalAlignment

Container

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Content">
            <array>
                <item>
                    <struct>
                        <item name="Key">
                            <string/>
                        </item>
                        <item name="Type">
                            <string/>
                        </item>
                        <item name="IsVector">
                            <bool/>
                        </item>
                        <item name="Value">
                            <any_of>
                                <item>
                                    <int signed="true" width="64"/>
                                </item>
                                <item>
                                    <int signed="false" width="64"/>
                                </item>
                                <item>
                                    <float width="64"/>
                                </item>
                                <item>
                                    <bool/>
                                </item>
                                <item>
                                    <string/>
                                </item>
                                <item>
                                    <polymorphic/>
                                </item>
                                <item>
                                    <array>
                                        <item>
                                            <int signed="true" width="64"/>
                                        </item>
                                    </array>
                                </item>
                                <item>
                                    <array>
                                        <item>
                                            <int signed="false" width="64"/>
                                        </item>
                                    </array>
                                </item>
                                <item>
                                    <array>
                                        <item>
                                            <float width="64"/>
                                        </item>
                                    </array>
                                </item>
                                <item>
                                    <array>
                                        <item>
                                            <bool/>
                                        </item>
                                    </array>
                                </item>
                                <item>
                                    <array>
                                        <item>
                                            <string/>
                                        </item>
                                    </array>
                                </item>
                                <item>
                                    <array>
                                        <item>
                                            <polymorphic/>
                                        </item>
                                    </array>
                                </item>
                            </any_of>
                        </item>
                    </struct>
                </item>
            </array>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Container",
  "data" : {
    "Content" : [ {
      "Key" : "valKey1",
      "Type" : "int",
      "IsVector" : false,
      "Value" : 5
    }, {
      "Key" : "valKey2",
      "Type" : "string",
      "IsVector" : false,
      "Value" : "stringval"
    }, {
      "Key" : "valKey3",
      "Type" : "object",
      "IsVector" : false,
      "Value" : {
        "class" : "MyObject",
        "data" : {
          "somevalue" : "stringval"
        }
      }
    }, {
      "Key" : "valKey4",
      "Type" : "float",
      "IsVector" : true,
      "Value" : [ 1.0, 2.0, 3.0 ]
    } ]
  }
}

DateTime

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="ExtendedUnixTime" desc="Unix time plus fraction of a second">
            <float width="64"/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "DateTime",
  "data" : {
    "ExtendedUnixTime" : 1.570779685528E9
  }
}

EncoderData

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Position" desc="Encoder position incremental value">
            <int signed="false" width="32"/>
        </item>
        <item name="Speed" desc="Speed in m/s">
            <float width="32"/>
        </item>
        <item name="SystemIncrement" desc="System increment value; application specific">
            <int signed="false" width="32"/>
        </item>
        <item name="TimestampUTC" desc="UTC time stamp in floating-point seconds">
            <float width="64"/>
        </item>
        <item name="TimestampUS" desc="Application specific, relative time stamp in microseconds">
            <int signed="false" width="64"/>
        </item>
        <item name="xValue" desc="Corresponding x-value if available. Application specific">
            <int signed="false" width="32"/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "EncoderData",
  "data" : {
    "Position" : 0,
    "Speed" : 0,
    "SystemIncrement" : 0,
    "TimestampUTC" : 0,
    "TimestampUS" : 0,
    "xValue" : 0
  }
}

Image

Directly referenced data formats

Parameters.Node.Array, Parameters.Node.Struct

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="PixelSize" desc="Size of the image pixel in some coordinate system (application defined). Usage is optional.">
            <data_format_ref name="Point3D"/>
        </item>
        <item name="Origin" desc="Application defined coordinate of the top left pixel. Usage is optional.">
            <data_format_ref name="Point3D"/>
        </item>
        <item name="HandleZeroPixels" desc="How pixels with value zero are interpreted">
            <any_of>
                <item desc="Pixels with value 0 are real pixels">
                    <string value="Default"/>
                </item>
                <item desc="Pixels with value 0 indicate missing data and are no 'real' value">
                    <string value="MissingData"/>
                </item>
            </any_of>
        </item>
        <item name="Data">
            <struct>
                <item name="ImageType">
                    <any_of>
                        <item>
                            <string value="uint8"/>
                        </item>
                        <item>
                            <string value="uint16"/>
                        </item>
                        <item>
                            <string value="uint32"/>
                        </item>
                        <item>
                            <string value="uint64"/>
                        </item>
                        <item>
                            <string value="int8"/>
                        </item>
                        <item>
                            <string value="int16"/>
                        </item>
                        <item>
                            <string value="int32"/>
                        </item>
                        <item>
                            <string value="int64"/>
                        </item>
                        <item>
                            <string value="float32"/>
                        </item>
                        <item>
                            <string value="float64"/>
                        </item>
                        <item>
                            <string value="RGB24"/>
                        </item>
                    </any_of>
                </item>
                <item name="Width">
                    <int signed="true" width="32"/>
                </item>
                <item name="Height">
                    <int signed="true" width="32"/>
                </item>
                <item name="Pixels">
                    <any_of>
                        <item>
                            <big_data_array>
                                <element_type name="uint8" desc="The pixel content"/>
                            </big_data_array>
                        </item>
                        <item>
                            <big_data_array>
                                <element_type name="uint16" desc="The pixel content"/>
                            </big_data_array>
                        </item>
                        <item>
                            <big_data_array>
                                <element_type name="uint32" desc="The pixel content"/>
                            </big_data_array>
                        </item>
                        <item>
                            <big_data_array>
                                <element_type name="uint64" desc="The pixel content"/>
                            </big_data_array>
                        </item>
                        <item>
                            <big_data_array>
                                <element_type name="int8" desc="The pixel content"/>
                            </big_data_array>
                        </item>
                        <item>
                            <big_data_array>
                                <element_type name="int16" desc="The pixel content"/>
                            </big_data_array>
                        </item>
                        <item>
                            <big_data_array>
                                <element_type name="int32" desc="The pixel content"/>
                            </big_data_array>
                        </item>
                        <item>
                            <big_data_array>
                                <element_type name="int64" desc="The pixel content"/>
                            </big_data_array>
                        </item>
                        <item>
                            <big_data_array>
                                <element_type name="float32" desc="The pixel content"/>
                            </big_data_array>
                        </item>
                        <item>
                            <big_data_array>
                                <element_type name="float64" desc="The pixel content"/>
                            </big_data_array>
                        </item>
                        <item>
                            <big_data_array>
                                <element_type name="uint8" desc="The BLUE pixel content"/>
                                <element_type name="uint8" desc="The GREEN pixel content"/>
                                <element_type name="uint8" desc="The RED pixel content"/>
                            </big_data_array>
                        </item>
                    </any_of>
                </item>
            </struct>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Image",
  "data" : {
    "PixelSize" : {
      "x" : 1,
      "y" : 1,
      "z" : 1
    },
    "Origin" : {
      "x" : 0,
      "y" : 0,
      "z" : 0
    },
    "HandleZeroPixels" : "Default",
    "Data" : {
      "ImageType" : "RGB24",
      "Width" : 2,
      "Height" : 2,
      "Pixels" : {
        "numOfElems" : 4,
        "elemSz" : 3,
        "endian" : "neutral",
        "elemTypes" : [ "uint8", "uint8", "uint8" ],
        "data" : "AgEABQQDCAcGCwoJ"
      }
    }
  }
}

Image.Calibration.CameraModel

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="CameraID" desc="Unique camera identifier">
            <string/>
        </item>
        <item name="ImageWidth" desc="Image width for which the calibration is valid">
            <int signed="true" width="32"/>
        </item>
        <item name="ImageHeight" desc="Image height for which the calibration is valid">
            <int signed="true" width="32"/>
        </item>
        <item name="FocalDistance" desc="Distance from the camera to the plane of best image sharpness">
            <float width="64"/>
        </item>
        <item name="FocalDistanceUnit" desc="Focus distance unit (Default is mm)">
            <string/>
        </item>
        <item name="IntrinsicK">
            <array>
                <item>
                    <array>
                        <item>
                            <float width="64"/>
                        </item>
                    </array>
                </item>
            </array>
        </item>
        <item name="WorldToSensorDistortion">
            <array>
                <item>
                    <array>
                        <item>
                            <float width="64"/>
                        </item>
                    </array>
                </item>
            </array>
        </item>
        <item name="SensorToWorldDistortion">
            <array>
                <item>
                    <array>
                        <item>
                            <float width="64"/>
                        </item>
                    </array>
                </item>
            </array>
        </item>
        <item name="WorldToView">
            <array>
                <item>
                    <array>
                        <item>
                            <float width="64"/>
                        </item>
                    </array>
                </item>
            </array>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Image.Calibration.CameraModel",
  "data" : {
    "CameraID" : "",
    "ImageWidth" : 0,
    "ImageHeight" : 0,
    "FocalDistance" : 0,
    "FocalDistanceUnit" : "",
    "IntrinsicK" : [ [ 1, 0, 0 ], [ 0, 1, 0 ], [ 0, 0, 1 ] ],
    "WorldToSensorDistortion" : [ [ 0 ], [ 0 ], [ 0 ], [ 0 ], [ 0 ] ],
    "SensorToWorldDistortion" : [ [ 0 ], [ 0 ], [ 0 ], [ 0 ], [ 0 ] ],
    "WorldToView" : [ [ 1, 0, 0, 0 ], [ 0, 1, 0, 0 ], [ 0, 0, 1, 0 ], [ 0, 0, 0, 1 ] ]
  }
}

Image.Fixture

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="PointsNames">
            <array>
                <item>
                    <string/>
                </item>
            </array>
        </item>
        <item name="Points">
            <array>
                <item>
                    <struct>
                        <item name="x">
                            <float width="64"/>
                        </item>
                        <item name="y">
                            <float width="64"/>
                        </item>
                    </struct>
                </item>
            </array>
        </item>
        <item name="ShapesNames">
            <array>
                <item>
                    <string/>
                </item>
            </array>
        </item>
        <item name="Shapes">
            <array>
                <item>
                    <polymorphic/>
                </item>
            </array>
        </item>
        <item name="CompositeShapesNames">
            <array>
                <item>
                    <string/>
                </item>
            </array>
        </item>
        <item name="CompositeShapes">
            <array>
                <item>
                    <polymorphic/>
                </item>
            </array>
        </item>
        <item name="AnglesNames">
            <array>
                <item>
                    <string/>
                </item>
            </array>
        </item>
        <item name="Angles">
            <array>
                <item>
                    <float width="64"/>
                </item>
            </array>
        </item>
        <item name="PosesNames">
            <array>
                <item>
                    <string/>
                </item>
            </array>
        </item>
        <item name="Poses">
            <array>
                <item>
                    <polymorphic/>
                </item>
            </array>
        </item>
        <item name="TeachPoseSet">
            <bool/>
        </item>
        <item name="TransformSet">
            <bool/>
        </item>
        <item name="TeachToMatch">
            <polymorphic/>
        </item>
        <item name="TeachToModel">
            <polymorphic/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Image.Fixture",
  "data" : {
    "PointsNames" : [ "thePoint_0", "thePoint_1" ],
    "Points" : [ {
      "x" : 50,
      "y" : 1000
    }, {
      "x" : 51,
      "y" : 1001
    } ],
    "ShapesNames" : [ "theShape_0", "theShape_1" ],
    "Shapes" : [ "Shape.Circle", "Shape.Line" ],
    "CompositeShapesNames" : [ "theCompositeShape_0", "theCompositeShape_1" ],
    "CompositeShapes" : [ "Shape.Composite", "Shape.Composite" ],
    "AnglesNames" : [ "theAngle_0", "theAngle_1" ],
    "Angles" : [ 1.1, 1.2 ],
    "PosesNames" : [ "thePose_0", "thePose_1" ],
    "Pose" : [ "Transform2D", "Transform2D" ],
    "TeachPoseSet" : "true",
    "TransformSet" : "true",
    "TeachToMatch" : "Transform2D",
    "TeachToModel" : "Transform2D"
  }
}

Image.Fixture3D

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="PointsNames">
            <array>
                <item>
                    <string/>
                </item>
            </array>
        </item>
        <item name="Points">
            <array>
                <item>
                    <struct>
                        <item name="x">
                            <float width="64"/>
                        </item>
                        <item name="y">
                            <float width="64"/>
                        </item>
                        <item name="z">
                            <float width="64"/>
                        </item>
                    </struct>
                </item>
            </array>
        </item>
        <item name="ShapesNames">
            <array>
                <item>
                    <string/>
                </item>
            </array>
        </item>
        <item name="Shapes">
            <array>
                <item>
                    <polymorphic/>
                </item>
            </array>
        </item>
        <item name="PosesNames">
            <array>
                <item>
                    <string/>
                </item>
            </array>
        </item>
        <item name="Poses">
            <array>
                <item>
                    <polymorphic/>
                </item>
            </array>
        </item>
        <item name="TeachPoseSet">
            <bool/>
        </item>
        <item name="TransformSet">
            <bool/>
        </item>
        <item name="TeachToMatch">
            <polymorphic/>
        </item>
        <item name="TeachToModel">
            <polymorphic/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Image.Fixture3D",
  "data" : {
    "PointsNames" : [ "thePoint_0", "thePoint_1" ],
    "Points" : [ {
      "x" : 50,
      "y" : 1000
    }, {
      "x" : 51,
      "y" : 1001
    } ],
    "ShapesNames" : [ "theShape_0", "theShape_1" ],
    "Shapes" : [ "Shape.Circle", "Shape.Line" ],
    "PosesNames" : [ "thePose_0", "thePose_1" ],
    "Pose" : [ "Transform3D", "Transform3D" ],
    "TeachPoseSet" : "true",
    "TransformSet" : "true",
    "TeachToMatch" : "Transform3D",
    "TeachToModel" : "Transform3D"
  }
}

Image.Matching.EdgeMatcher

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Version">
            <int signed="true" width="32"/>
        </item>
        <item name="Params">
            <struct>
                <item name="EdgeThreshold">
                    <struct>
                        <item name="x">
                            <float width="64"/>
                        </item>
                        <item name="y">
                            <float width="64"/>
                        </item>
                    </struct>
                </item>
                <item name="ProcessingUnit">
                    <int signed="true" width="32"/>
                </item>
            </struct>
        </item>
        <item name="TimeoutSeconds">
            <float width="64"/>
        </item>
        <item name="Matcher">
            <string/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Image.Matching.EdgeMatcher",
  "data" : {
    "Params" : {
      "Version" : 2,
      "EdgeThreshold" : {
        "x" : 50,
        "y" : 1000
      },
      "ProcessingUnit" : 1
    },
    "TimeoutSeconds" : 5,
    "Matcher" : "aa"
  }
}

Image.Matching.EdgeMatcher3D

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Version">
            <int signed="true" width="32"/>
        </item>
        <item name="Params">
            <struct>
                <item name="EdgeThreshold">
                    <struct>
                        <item name="x">
                            <float width="64"/>
                        </item>
                        <item name="y">
                            <float width="64"/>
                        </item>
                    </struct>
                </item>
                <item name="ProcessingUnit">
                    <int signed="true" width="32"/>
                </item>
            </struct>
        </item>
        <item name="TimeoutSeconds">
            <float width="64"/>
        </item>
        <item name="ReferencePlaneSet">
            <bool/>
        </item>
        <item name="Matcher">
            <string/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Image.Matching.EdgeMatcher3D",
  "data" : {
    "Version" : 2,
    "Params" : {
      "EdgeThreshold" : {
        "x" : 50,
        "y" : 1000
      },
      "ProcessingUnit" : 1
    },
    "TimeoutSeconds" : 5,
    "ReferencePlaneSet" : true,
    "Matcher" : "aa"
  }
}

Image.Matching.PointMatcher

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Version">
            <int signed="true" width="32"/>
        </item>
        <item name="Matcher">
            <string/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Image.Matching.PointMatcher",
  "data" : {
    "Version" : 2,
    "Matcher" : "aa"
  }
}

Image.PixelRegion

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="segments" desc="Structs for individual segments of a run-length coded region">
            <big_data_array>
                <element_type name="int32" desc="y: Image row of the segment"/>
                <element_type name="int32" desc="xStart: x-coordinate of first included pixel"/>
                <element_type name="int32" desc="xStop: x-coordinate of last included pixel"/>
            </big_data_array>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Image.PixelRegion",
  "data" : {
    "segments" : {
      "numOfElems" : 2,
      "elemSz" : 12,
      "endian" : "little",
      "elemTypes" : [ "int32", "int32", "int32" ],
      "data" : "AQAAAAIAAAADAAAABAAAAAUAAAAGAAAA"
    }
  }
}

MachineLearning.DataSet

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Revision">
            <int signed="true" width="32"/>
        </item>
        <item name="Width">
            <int signed="true" width="32"/>
        </item>
        <item name="Height">
            <int signed="true" width="32"/>
        </item>
        <item name="LabelType">
            <any_of>
                <item>
                    <string value="Classification"/>
                </item>
                <item>
                    <string value="Regression"/>
                </item>
            </any_of>
        </item>
        <item name="WeightsExist">
            <bool/>
        </item>
        <item name="Samples">
            <big_data_array>
                <element_type name="float32"/>
            </big_data_array>
        </item>
        <item name="Labels">
            <any_of>
                <item>
                    <big_data_array>
                        <element_type name="float32"/>
                    </big_data_array>
                </item>
                <item>
                    <big_data_array>
                        <element_type name="int32"/>
                    </big_data_array>
                </item>
            </any_of>
        </item>
        <item name="Weights">
            <big_data_array>
                <element_type name="float32"/>
            </big_data_array>
        </item>
    </struct>
</item>

Sample

{
  "class" : "MachineLearning.DataSet",
  "data" : {
    "Revision" : 0,
    "Width" : 0,
    "Height" : 0,
    "LabelType" : "Classification",
    "WeightsExist" : false,
    "Samples" : {
      "numOfElems" : 0,
      "elemSz" : 4,
      "endian" : "little",
      "elemTypes" : [ "float32" ],
      "data" : ""
    },
    "Labels" : {
      "numOfElems" : 0,
      "elemSz" : 4,
      "endian" : "little",
      "elemTypes" : [ "int32" ],
      "data" : ""
    },
    "Weights" : {
      "numOfElems" : 0,
      "elemSz" : 4,
      "endian" : "little",
      "elemTypes" : [ "float32" ],
      "data" : ""
    }
  }
}

Matrix

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Rows" desc="Matrix height (in number of elements)">
            <int signed="true" width="32"/>
        </item>
        <item name="Columns" desc="Matrix width (in number of elements)">
            <int signed="true" width="32"/>
        </item>
        <item name="Elements" desc="Matrix elements in row-major storage order">
            <big_data_array>
                <element_type name="float64" desc="Single matrix element"/>
            </big_data_array>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Matrix",
  "data" : {
    "Rows" : 2,
    "Columns" : 2,
    "Elements" : {
      "numOfElems" : 4,
      "elemSz" : 8,
      "endian" : "little",
      "elemTypes" : [ "float64" ],
      "data" : "kiRJkiRJwj+SJEmSJEnSP9u2bdu2bds/kiRJkiRJ4j8="
    }
  }
}

Mesh

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Indices" desc="List of triangle indices">
            <big_data_array>
                <element_type name="uint32" desc="Vertex index"/>
            </big_data_array>
        </item>
        <item name="Vertices" desc="Vertex position coordinates">
            <big_data_array>
                <element_type name="float32" desc="X coordinate"/>
                <element_type name="float32" desc="Y coordinate"/>
                <element_type name="float32" desc="Z coordinate"/>
            </big_data_array>
        </item>
        <item name="Normals" desc="Vertex normal vectors">
            <big_data_array>
                <element_type name="float32" desc="X coordinate"/>
                <element_type name="float32" desc="Y coordinate"/>
                <element_type name="float32" desc="Z coordinate"/>
            </big_data_array>
        </item>
        <item name="Colors" desc="Vertex color vectors">
            <big_data_array>
                <element_type name="uint8" desc="Red"/>
                <element_type name="uint8" desc="Green"/>
                <element_type name="uint8" desc="Blue"/>
                <element_type name="uint8" desc="Alpha"/>
            </big_data_array>
        </item>
        <item name="Intensities" desc="Vertex intensities">
            <big_data_array>
                <element_type name="float32" desc="Intensity"/>
            </big_data_array>
        </item>
        <item name="TexCoords" desc="Vertex texture coordinates">
            <big_data_array>
                <element_type name="float32" desc="S coordinate"/>
                <element_type name="float32" desc="T coordinate"/>
            </big_data_array>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Mesh",
  "data" : {
    "Indices" : {
      "numOfElems" : 6,
      "elemSz" : 4,
      "endian" : "little",
      "elemTypes" : [ "uint32" ],
      "data" : "AAAAAAEAAAACAAAAAQAAAAIAAAADAAAA"
    },
    "Vertices" : {
      "numOfElems" : 4,
      "elemSz" : 12,
      "endian" : "little",
      "elemTypes" : [ "float32", "float32", "float32" ],
      "data" : "AAAAAAAAAAAAAAAAAAAAAAAAgD8AAAAAAACAPwAAAAAAAAAAAACAPwAAgD8AAAAA"
    },
    "Normals" : {
      "numOfElems" : 4,
      "elemSz" : 12,
      "endian" : "little",
      "elemTypes" : [ "float32", "float32", "float32" ],
      "data" : "AAAAAAAAAAAAAIA/AAAAAAAAAAAAAIA/AAAAAAAAAAAAAIA/AAAAAAAAAAAAAIA/"
    },
    "Colors" : {
      "numOfElems" : 4,
      "elemSz" : 4,
      "endian" : "neutral",
      "elemTypes" : [ "uint8", "uint8", "uint8", "uint8" ],
      "data" : "/wAA////AP///wD/AP8A/w=="
    },
    "Intensities" : {
      "numOfElems" : 4,
      "elemSz" : 4,
      "endian" : "little",
      "elemTypes" : [ "float32" ],
      "data" : "zczMPc3MTD6amZk+zczMPg=="
    },
    "TexCoords" : {
      "numOfElems" : 4,
      "elemSz" : 8,
      "endian" : "little",
      "elemTypes" : [ "float32", "float32" ],
      "data" : "AAAAAAAAAAAAAAAAAACAPwAAgD8AAAAAAAAAAAAAgD8="
    }
  }
}

Parameters.Node

Directly referenced data formats

Parameters.Node.Variant

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="type">
            <any_of>
                <item>
                    <string value="SInt"/>
                </item>
                <item>
                    <string value="Int"/>
                </item>
                <item>
                    <string value="DInt"/>
                </item>
                <item>
                    <string value="LInt"/>
                </item>
                <item>
                    <string value="USInt"/>
                </item>
                <item>
                    <string value="UInt"/>
                </item>
                <item>
                    <string value="UDInt"/>
                </item>
                <item>
                    <string value="ULInt"/>
                </item>
                <item>
                    <string value="Real"/>
                </item>
                <item>
                    <string value="LReal"/>
                </item>
                <item>
                    <string value="Bool"/>
                </item>
                <item>
                    <string value="String"/>
                </item>
                <item>
                    <string value="Array"/>
                </item>
                <item>
                    <string value="Struct"/>
                </item>
            </any_of>
        </item>
        <item name="value">
            <data_format_ref name="Parameters.Node.Variant"/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Parameters.Node",
  "data" : {
    "type" : "Int",
    "value" : 0
  }
}

Parameters.Node.Array

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="type">
            <string/>
        </item>
        <item name="value">
            <array>
                <item>
                    <data_format_ref name="Parameters.Node.Variant"/>
                </item>
            </array>
        </item>
    </struct>
</item>

Sample

{
  "type" : "Int",
  "value" : [ 1, 1, 3 ]
}

Parameters.Node.Struct

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <array>
        <item>
            <struct>
                <item name="name">
                    <string/>
                </item>
                <item name="type">
                    <any_of>
                        <item>
                            <string value="SInt"/>
                        </item>
                        <item>
                            <string value="Int"/>
                        </item>
                        <item>
                            <string value="DInt"/>
                        </item>
                        <item>
                            <string value="LInt"/>
                        </item>
                        <item>
                            <string value="USInt"/>
                        </item>
                        <item>
                            <string value="UInt"/>
                        </item>
                        <item>
                            <string value="UDInt"/>
                        </item>
                        <item>
                            <string value="ULInt"/>
                        </item>
                        <item>
                            <string value="Real"/>
                        </item>
                        <item>
                            <string value="LReal"/>
                        </item>
                        <item>
                            <string value="Bool"/>
                        </item>
                        <item>
                            <string value="String"/>
                        </item>
                        <item>
                            <string value="Array"/>
                        </item>
                        <item>
                            <string value="Struct"/>
                        </item>
                    </any_of>
                </item>
                <item name="value">
                    <data_format_ref name="Parameters.Node.Variant"/>
                </item>
            </struct>
        </item>
    </array>
</item>

Sample

[ {
  "name" : "member1",
  "type" : "Int",
  "value" : 1
} ]

Parameters.Node.Variant

Directly referenced data formats

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <any_of>
        <item>
            <int signed="true" width="64"/>
        </item>
        <item>
            <int signed="false" width="64"/>
        </item>
        <item>
            <float width="64"/>
        </item>
        <item>
            <bool/>
        </item>
        <item>
            <string/>
        </item>
        <item>
            <data_format_ref name="Parameters.Node.Struct"/>
        </item>
        <item>
            <data_format_ref name="Parameters.Node.Array"/>
        </item>
    </any_of>
</item>

Sample

Point

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <polymorphic>
        <data_format_ref name="Point2D"/>
        <data_format_ref name="Point3D"/>
    </polymorphic>
</item>

Point2D

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="x" desc="X coordinate">
            <float width="64"/>
        </item>
        <item name="y" desc="Y coordinate">
            <float width="64"/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Point2D",
  "data" : {
    "x" : 1.0,
    "y" : 2.0
  }
}

Point3D

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="x" desc="X coordinate">
            <float width="64"/>
        </item>
        <item name="y" desc="Y coordinate">
            <float width="64"/>
        </item>
        <item name="z" desc="Z coordinate">
            <float width="64"/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Point3D",
  "data" : {
    "x" : 1.0,
    "y" : 2.0,
    "z" : 3.0
  }
}

Point3D_32

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="x" desc="X coordinate">
            <float width="32"/>
        </item>
        <item name="y" desc="Y coordinate">
            <float width="32"/>
        </item>
        <item name="z" desc="Z coordinate">
            <float width="32"/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Point3D_32",
  "data" : {
    "x" : 1.0,
    "y" : 2.0,
    "z" : 3.0
  }
}

PointCloud

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <polymorphic>
        <data_format_ref name="PointCloud.XYZI"/>
    </polymorphic>
</item>

PointCloud.XYZI

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Width" desc="Width of the data matrix if organized, total size if not">
            <int signed="true" width="32"/>
        </item>
        <item name="Height" desc="Height of the data matrix if organized, 1 if not">
            <int signed="true" width="32"/>
        </item>
        <item name="IsDense" desc="True if no points are invalid">
            <bool/>
        </item>
        <item name="ColorMode" desc="Point cloud color mode">
            <any_of>
                <item>
                    <string value="INTENSITY"/>
                </item>
                <item>
                    <string value="RGBA"/>
                </item>
            </any_of>
        </item>
        <item name="Number" desc="Point cloud identifier (e.g. object ID or sequence number)">
            <int signed="false" width="32"/>
        </item>
        <item name="TimeStamp" desc="Time stamp in microseconds">
            <int signed="false" width="32"/>
        </item>
        <item name="SensorIDs" desc="ID(s) of the sensor(s)">
            <array>
                <item>
                    <int signed="false" width="32"/>
                </item>
            </array>
        </item>
        <item name="SensorPositions" desc="Position of the sensor(s) (x, y, z in mm)">
            <array>
                <item>
                    <data_format_ref name="Point3D_32"/>
                </item>
            </array>
        </item>
        <item name="SensorOrientations" desc="Orientation of the sensor(s) (yaw, pitch, roll in radians)">
            <array>
                <item>
                    <data_format_ref name="Point3D_32"/>
                </item>
            </array>
        </item>
        <item name="Points" desc="Each point has a size of 16 bytes, the format of the last 4 bytes depends on the ColorMode">
            <any_of>
                <item>
                    <big_data_array>
                        <element_type name="float32" desc="X coordinate"/>
                        <element_type name="float32" desc="Y coordinate"/>
                        <element_type name="float32" desc="Z coordinate"/>
                        <element_type name="float32" desc="Intensity value"/>
                    </big_data_array>
                </item>
                <item>
                    <big_data_array>
                        <element_type name="float32" desc="X coordinate"/>
                        <element_type name="float32" desc="Y coordinate"/>
                        <element_type name="float32" desc="Z coordinate"/>
                        <element_type name="uint8" desc="Red"/>
                        <element_type name="uint8" desc="Green"/>
                        <element_type name="uint8" desc="Blue"/>
                        <element_type name="uint8" desc="Alpha"/>
                    </big_data_array>
                </item>
            </any_of>
        </item>
    </struct>
</item>

Sample

{
  "class" : " PointCloud.XYZI",
  "data" : {
    "Width" : 2,
    "Height" : 1,
    "IsDense" : true,
    "ColorMode" : "INTENSITY",
    "Number" : 42,
    "TimeStamp" : 2880154539,
    "SensorIDs" : [ 1, 2 ],
    "SensorPositions" : [ {
      "x" : 1,
      "y" : 2,
      "z" : 3
    }, {
      "x" : 7,
      "y" : 8,
      "z" : 9
    } ],
    "SensorOrientations" : [ {
      "x" : 4,
      "y" : 5,
      "z" : 6
    }, {
      "x" : 10,
      "y" : 11,
      "z" : 12
    } ],
    "Points" : {
      "numOfElems" : 2,
      "elemSz" : 16,
      "endian" : "little",
      "elemTypes" : [ "float32", "float32", "float32", "float32" ],
      "data" : "AACAPwAAAEAAAEBAAACAPwAAgEAAAKBAAADAQAAAgD8="
    }
  }
}

Profile

Directly referenced data formats

Point2D

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="IsClosed">
            <bool/>
        </item>
        <item name="UseValidFlags">
            <bool/>
        </item>
        <item name="Values">
            <array>
                <item>
                    <float width="32"/>
                </item>
            </array>
        </item>
        <item name="ValidFlags">
            <array>
                <item>
                    <int signed="false" width="8"/>
                </item>
            </array>
        </item>
        <item name="StartImplicit1D">
            <float width="64"/>
        </item>
        <item name="DeltaImplicit1D">
            <float width="64"/>
        </item>
        <item name="CoordinatesExplicit1D">
            <array>
                <item>
                    <float width="32"/>
                </item>
            </array>
        </item>
        <item name="StartImplicit2D">
            <data_format_ref name="Point2D"/>
        </item>
        <item name="DeltaImplicit2D">
            <data_format_ref name="Point2D"/>
        </item>
        <item name="CoordinatesExplicit2D">
            <array>
                <item>
                    <data_format_ref name="Point2D"/>
                </item>
            </array>
        </item>
        <item name="CoordinateType">
            <any_of>
                <item>
                    <string value="IMPLICIT_1D"/>
                </item>
                <item>
                    <string value="EXPLICIT_1D"/>
                </item>
                <item>
                    <string value="IMPLICIT_2D"/>
                </item>
                <item>
                    <string value="EXPLICIT_2D"/>
                </item>
            </any_of>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Profile",
  "data" : {
    "IsClosed" : false,
    "UseValidFlags" : true,
    "Values" : [ 2, 2, 2 ],
    "ValidFlags" : [ 1, 1, 1 ],
    "StartImplicit1D" : 0,
    "DeltaImplicit1D" : 1,
    "CoordinatesExplicit1D" : [ 0, 1, 2 ],
    "StartImplicit2D" : {
      "x" : 0,
      "y" : 0
    },
    "DeltaImplicit2D" : {
      "x" : 1,
      "y" : 0
    },
    "CoordinatesExplicit2D" : [ ],
    "CoordinateType" : "EXPLICIT_1D"
  }
}

Profile.Curve

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <polymorphic>
        <data_format_ref name="Profile.Curve.Polynomial"/>
        <data_format_ref name="Profile.Curve.Exponential"/>
        <data_format_ref name="Profile.Curve.Gaussian"/>
    </polymorphic>
</item>

Sample

{
  "class" : "Profile.Curve.Polynomial",
  "data" : {
    "coefficients" : [ 1.0, 2.0, 3.0 ]
  }
}

Profile.Curve.Exponential

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Coefficients">
            <array length="3">
                <item>
                    <float width="64"/>
                </item>
            </array>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Profile.Curve.Exponential",
  "data" : {
    "Coefficients" : [ 1.0, 2.0, 3.0 ]
  }
}

Profile.Curve.Gaussian

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Coefficients">
            <array length="4">
                <item>
                    <float width="64"/>
                </item>
            </array>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Profile.Curve.Gaussian",
  "data" : {
    "Coefficients" : [ 1.0, 2.0, 3.0, 4.0 ]
  }
}

Profile.Curve.Polynomial

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Coefficients">
            <array>
                <item>
                    <float width="64"/>
                </item>
            </array>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Profile.Curve.Polynomial",
  "data" : {
    "Coefficients" : [ 1.0, 2.0, 3.0 ]
  }
}

Profile.Log

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="RecentValuesEnabled">
            <bool/>
        </item>
        <item name="Values">
            <array>
                <item>
                    <float width="32"/>
                </item>
            </array>
        </item>
        <item name="Coordinates">
            <array>
                <item>
                    <float width="32"/>
                </item>
            </array>
        </item>
        <item name="Count">
            <int signed="false" width="64"/>
        </item>
        <item name="M2">
            <float width="64"/>
        </item>
        <item name="Mean">
            <float width="64"/>
        </item>
        <item name="Min">
            <float width="32"/>
        </item>
        <item name="MinCoord">
            <float width="32"/>
        </item>
        <item name="Max">
            <float width="32"/>
        </item>
        <item name="MaxCoord">
            <float width="32"/>
        </item>
        <item name="HistogramEnabled">
            <bool/>
        </item>
        <item name="Histogram">
            <array>
                <item>
                    <float width="32"/>
                </item>
            </array>
        </item>
        <item name="HistogramMinValue">
            <float width="32"/>
        </item>
        <item name="HistogramDelta">
            <float width="32"/>
        </item>
        <item name="RecentBack">
            <int signed="false" width="unspecified"/>
        </item>
        <item name="HistoricStatisticsEnabled">
            <bool/>
        </item>
        <item name="HistoricValueBuffer">
            <array>
                <item>
                    <float width="32"/>
                </item>
            </array>
        </item>
        <item name="HistoricCoordBuffer">
            <array>
                <item>
                    <float width="32"/>
                </item>
            </array>
        </item>
        <item name="HistoricCoordinates">
            <array>
                <item>
                    <float width="32"/>
                </item>
            </array>
        </item>
        <item name="HistoricMeanValues">
            <array>
                <item>
                    <float width="32"/>
                </item>
            </array>
        </item>
        <item name="HistoricStdDevValues">
            <array>
                <item>
                    <float width="32"/>
                </item>
            </array>
        </item>
        <item name="HistoricMaxValues">
            <array>
                <item>
                    <float width="32"/>
                </item>
            </array>
        </item>
        <item name="HistoricMinValues">
            <array>
                <item>
                    <float width="32"/>
                </item>
            </array>
        </item>
        <item name="HistoricQuanta">
            <int signed="false" width="64"/>
        </item>
        <item name="PeriodCount">
            <int signed="false" width="32"/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Profile.Log",
  "data" : {
    "RecentValuesEnabled" : false,
    "Values" : [ ],
    "Coordinates" : [ ],
    "Min" : -3.200000047,
    "MinCoord" : 3.140000104,
    "Max" : 1.200000047,
    "MaxCoord" : 0,
    "Mean" : -0.5666666626930237,
    "M2" : 10.806667106946314,
    "Count" : 3,
    "HistogramEnabled" : false,
    "Histogram" : [ ],
    "HistogramMinValue" : 0,
    "HistogramDelta" : 0,
    "RecentBack" : 0,
    "HistoricStatisticsEnabled" : true,
    "HistoricValueBuffer" : [ 0.300000011 ],
    "HistoricCoordBuffer" : [ 0 ],
    "HistoricCoordinates" : [ 1.570000052 ],
    "HistoricMeanValues" : [ -1 ],
    "HistoricStdDevValues" : [ 2.200000047 ],
    "HistoricMaxValues" : [ 1.200000047 ],
    "HistoricMinValues" : [ -3.200000047 ],
    "HistoricQuanta" : 2,
    "PeriodCount" : 4
  }
}

SensorData

Directly referenced data formats

EncoderData

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Encoder" desc="Encoder data. May be optional and filled with default values when not available">
            <data_format_ref name="EncoderData"/>
        </item>
        <item name="Timestamp" desc="Application specific time stamp in microseconds">
            <int signed="false" width="64"/>
        </item>
        <item name="FrameNo" desc="Capture driver specific frame number">
            <int signed="false" width="32"/>
        </item>
        <item name="Ident" desc="Application specific ID where the corresponding image can be assigned to. Is -1 when not used or invalid.">
            <int signed="true" width="32"/>
        </item>
        <item name="Origin" desc="Dot separated list of image providers where the image originated from">
            <string/>
        </item>
        <item name="Name" desc="Name of the corresponding data object">
            <string/>
        </item>
        <item name="MetaData">
            <polymorphic can_be_null="true">
                <data_format_ref name="Container"/>
            </polymorphic>
        </item>
    </struct>
</item>

Sample

{
  "class" : "SensorData",
  "data" : {
    "Encoder" : {
      "Position" : 0,
      "Speed" : 0,
      "SystemIncrement" : 0,
      "TimestampUTC" : 0,
      "TimestampUS" : 0,
      "xValue" : 0
    },
    "Timestamp" : 0,
    "FrameNo" : 0,
    "Ident" : -1,
    "Origin" : "",
    "Name" : ""
  }
}

Shape

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <polymorphic>
        <data_format_ref name="Shape.Arc"/>
        <data_format_ref name="Shape.Circle"/>
        <data_format_ref name="Shape.Composite"/>
        <data_format_ref name="Shape.Ellipse"/>
        <data_format_ref name="Shape.Line"/>
        <data_format_ref name="Shape.LineSegment"/>
        <data_format_ref name="Shape.PolyLine"/>
        <data_format_ref name="Shape.Rectangle"/>
        <data_format_ref name="Shape.Sector"/>
    </polymorphic>
</item>

Sample

{
  "class" : "Shape.Circle",
  "data" : {
    "cx" : 0.0,
    "cy" : 1.0,
    "radius" : 2.0
  }
}

Shape.Arc

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="cx" desc="Center point X coordinate">
            <float width="64"/>
        </item>
        <item name="cy" desc="Center point Y coordinate">
            <float width="64"/>
        </item>
        <item name="radius" desc="Radius">
            <float width="64"/>
        </item>
        <item name="angle" desc="Initial angle of the arc in radians">
            <float width="64"/>
        </item>
        <item name="deltaAngle" desc="Angular size of the arc in radians">
            <float width="64"/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Shape.Arc",
  "data" : {
    "cx" : 10.0,
    "cy" : 10.0,
    "radius" : 1.0,
    "angle" : 0.0,
    "deltaAngle" : 3.1415927
  }
}

Shape.Circle

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="cx" desc="Center point X coordinate">
            <float width="64"/>
        </item>
        <item name="cy" desc="Center point Y coordinate">
            <float width="64"/>
        </item>
        <item name="radius" desc="Radius">
            <float width="64"/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Shape.Circle",
  "data" : {
    "cx" : 0.0,
    "cy" : 1.0,
    "radius" : 2.0
  }
}

Shape.Composite

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="shapes">
            <array>
                <item>
                    <struct>
                        <item name="isPositive">
                            <bool/>
                        </item>
                        <item name="shape">
                            <data_format_ref name="Shape"/>
                        </item>
                    </struct>
                </item>
            </array>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Shape.Composite",
  "data" : {
    "shapes" : [ {
      "isPositive" : true,
      "shape" : {
        "class" : "Shape.Circle",
        "data" : {
          "cx" : 1,
          "cy" : 2,
          "radius" : 3
        }
      }
    }, {
      "isPositive" : false,
      "shape" : {
        "class" : "Shape.Circle",
        "data" : {
          "cx" : 2,
          "cy" : 3,
          "radius" : 4
        }
      }
    } ]
  }
}

Shape.Ellipse

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="cx" desc="Center point X coordinate">
            <float width="64"/>
        </item>
        <item name="cy" desc="Center point Y coordinate">
            <float width="64"/>
        </item>
        <item name="radiusX" desc="Radius in X direction">
            <float width="64"/>
        </item>
        <item name="radiusY" desc="Radius in Y direction">
            <float width="64"/>
        </item>
        <item name="orientationRad" desc="Orientation angle in radians">
            <float width="64"/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Shape.Ellipse",
  "data" : {
    "cx" : 1.0,
    "cy" : 2.0,
    "radiusX" : 3.0,
    "radiusY" : 4.0,
    "orientationRad" : 0.0
  }
}

Shape.Line

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="x1" desc="Line starting point X coordinate">
            <float width="64"/>
        </item>
        <item name="y1" desc="Line starting point Y coordinate">
            <float width="64"/>
        </item>
        <item name="xDir" desc="Direction vector X coordinate">
            <float width="64"/>
        </item>
        <item name="yDir" desc="Direction vector Y coordinate">
            <float width="64"/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Shape.Line",
  "data" : {
    "x1" : 1.0,
    "y1" : 2.0,
    "xDir" : 1.0,
    "yDir" : 1.0
  }
}

Shape.LineSegment

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="x1" desc="Line starting point X coordinate">
            <float width="64"/>
        </item>
        <item name="y1" desc="Line starting point Y coordinate">
            <float width="64"/>
        </item>
        <item name="x2" desc="Line ending point X coordinate">
            <float width="64"/>
        </item>
        <item name="y2" desc="Line ending point X coordinate">
            <float width="64"/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Shape.LineSegment",
  "data" : {
    "x1" : 1.0,
    "y1" : 2.0,
    "x2" : 2.0,
    "y2" : 3.0
  }
}

Shape.PolyLine

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="points">
            <array>
                <item>
                    <data_format_ref name="Point2D"/>
                </item>
            </array>
        </item>
        <item name="isClosed">
            <bool/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Shape.PolyLine",
  "data" : {
    "points" : [ {
      "x" : 1.0,
      "y" : 2.0
    }, {
      "x" : 3.0,
      "y" : 4.0
    } ],
    "isClosed" : false
  }
}

Shape.Rectangle

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="cx" desc="Center point X coordinate">
            <float width="64"/>
        </item>
        <item name="cy" desc="Center point Y coordinate">
            <float width="64"/>
        </item>
        <item name="width" desc="Rectangle width">
            <float width="64"/>
        </item>
        <item name="height" desc="Rectangle height">
            <float width="64"/>
        </item>
        <item name="orientationRad" desc="Orientation angle in radians">
            <float width="64"/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Shape.Rectangle",
  "data" : {
    "cx" : 1.0,
    "cy" : 2.0,
    "width" : 3.0,
    "height" : 4.0,
    "orientationRad" : 0.0
  }
}

Shape.Sector

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="cx" desc="Center point X coordinate">
            <float width="64"/>
        </item>
        <item name="cy" desc="Center point Y coordinate">
            <float width="64"/>
        </item>
        <item name="innerRadius" desc="Inner radius of the sector">
            <float width="64"/>
        </item>
        <item name="outerRadius" desc="Outer radius of the sector">
            <float width="64"/>
        </item>
        <item name="angle" desc="Initial angle of the arc in radians">
            <float width="64"/>
        </item>
        <item name="deltaAngle" desc="Angular size of the arc in radians">
            <float width="64"/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Shape.Sector",
  "data" : {
    "cx" : 10.0,
    "cy" : 10.0,
    "innerRadius" : 1.0,
    "outerRadius" : 2.0,
    "angle" : 0.0,
    "deltaAngle" : 3.1415927
  }
}

Shape3D

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <polymorphic>
        <data_format_ref name="Shape3D.Box"/>
        <data_format_ref name="Shape3D.Circle"/>
        <data_format_ref name="Shape3D.Cone"/>
        <data_format_ref name="Shape3D.Cylinder"/>
        <data_format_ref name="Shape3D.Ellipse"/>
        <data_format_ref name="Shape3D.EllipticCylinder"/>
        <data_format_ref name="Shape3D.Line"/>
        <data_format_ref name="Shape3D.LineSegment"/>
        <data_format_ref name="Shape3D.Plane"/>
        <data_format_ref name="Shape3D.Polygon"/>
        <data_format_ref name="Shape3D.Polyline"/>
        <data_format_ref name="Shape3D.Rectangle"/>
        <data_format_ref name="Shape3D.Sphere"/>
    </polymorphic>
</item>

Sample

{
  "class" : "Shape3D.Box",
  "data" : {
    "sizeX" : 10,
    "sizeY" : 11,
    "sizeZ" : 12,
    "pose" : {
      "Type" : "TRANSLATION",
      "Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
    }
  }
}

Shape3D.Box

Directly referenced data formats

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="sizeX" desc="Total extent of the box along its local x-direction">
            <float width="64"/>
        </item>
        <item name="sizeY" desc="Total extent of the box along its local y-direction">
            <float width="64"/>
        </item>
        <item name="sizeZ" desc="Total extent of the box along its local z-direction">
            <float width="64"/>
        </item>
        <item name="pose" desc="Position and orientation of the shape">
            <data_format_ref name="Transform3D"/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Shape3D.Box",
  "data" : {
    "sizeX" : 10,
    "sizeY" : 11,
    "sizeZ" : 12,
    "pose" : {
      "Type" : "TRANSLATION",
      "Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
    }
  }
}

Shape3D.Circle

Directly referenced data formats

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="radius" desc="Radius of the circle">
            <float width="64"/>
        </item>
        <item name="pose" desc="Position and orientation of the shape">
            <data_format_ref name="Transform3D"/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Shape3D.Circle",
  "data" : {
    "radius" : 10,
    "pose" : {
      "Type" : "TRANSLATION",
      "Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
    }
  }
}

Shape3D.Cone

Directly referenced data formats

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="radius" desc="Radius of the cone">
            <float width="64"/>
        </item>
        <item name="height" desc="Height of the cone along its local z-direction">
            <float width="64"/>
        </item>
        <item name="pose" desc="Position and orientation of the shape">
            <data_format_ref name="Transform3D"/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Shape3D.Cone",
  "data" : {
    "radius" : 10,
    "height" : 4,
    "pose" : {
      "Type" : "TRANSLATION",
      "Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
    }
  }
}

Shape3D.Cylinder

Directly referenced data formats

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="radius" desc="Radius of the cylinder">
            <float width="64"/>
        </item>
        <item name="height" desc="Height of the cylinder along its local z-direction">
            <float width="64"/>
        </item>
        <item name="pose" desc="Position and orientation of the shape">
            <data_format_ref name="Transform3D"/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Shape3D.Cylinder",
  "data" : {
    "radius" : 10,
    "height" : 4,
    "pose" : {
      "Type" : "TRANSLATION",
      "Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
    }
  }
}

Shape3D.Ellipse

Directly referenced data formats

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="radiusX" desc="Radius of the ellipse in the local x-direction">
            <float width="64"/>
        </item>
        <item name="radiusY" desc="Radius of the ellipse in the local y-direction">
            <float width="64"/>
        </item>
        <item name="pose" desc="Position and orientation of the shape">
            <data_format_ref name="Transform3D"/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Shape3D.Ellipse",
  "data" : {
    "radiusX" : 10,
    "radiusY" : 5,
    "pose" : {
      "Type" : "TRANSLATION",
      "Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
    }
  }
}

Shape3D.EllipticCylinder

Directly referenced data formats

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="radiusX" desc="Radius of the elliptic cylinder in the local x-direction">
            <float width="64"/>
        </item>
        <item name="radiusY" desc="Radius of the elliptic cylinder in the local y-direction">
            <float width="64"/>
        </item>
        <item name="height" desc="Height of the elliptic cylinder in the local z-direction">
            <float width="64"/>
        </item>
        <item name="pose" desc="Position and orientation of the shape">
            <data_format_ref name="Transform3D"/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Shape3D.EllipticCylinder",
  "data" : {
    "radiusX" : 10,
    "radiusY" : 5,
    "height" : 7,
    "pose" : {
      "Type" : "TRANSLATION",
      "Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
    }
  }
}

Shape3D.Line

Directly referenced data formats

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="point" desc="A point on the line">
            <data_format_ref name="Point3D"/>
        </item>
        <item name="direction" desc="The direction of the line, unit vector">
            <data_format_ref name="Point3D"/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Shape3D.Line",
  "data" : {
    "point" : {
      "x" : 11,
      "y" : 12,
      "z" : 13
    },
    "direction" : {
      "x" : 0,
      "y" : 1,
      "z" : 0
    }
  }
}

Shape3D.LineSegment

Directly referenced data formats

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="point1" desc="The first end point of the line segment">
            <data_format_ref name="Point3D"/>
        </item>
        <item name="point2" desc="The other end point of the line segment">
            <data_format_ref name="Point3D"/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Shape3D.LineSegment",
  "data" : {
    "point1" : {
      "x" : 11,
      "y" : 12,
      "z" : 13
    },
    "point2" : {
      "x" : 10,
      "y" : -2,
      "z" : 0
    }
  }
}

Shape3D.Plane

Directly referenced data formats

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="normal" desc="The plane normal">
            <data_format_ref name="Point3D"/>
        </item>
        <item name="distance" desc="The distance from the origin to the plane">
            <float width="64"/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Shape3D.Plane",
  "data" : {
    "normal" : {
      "x" : 11,
      "y" : 12,
      "z" : 13
    },
    "distance" : 5
  }
}

Shape3D.Polygon

Directly referenced data formats

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="points">
            <array>
                <item>
                    <data_format_ref name="Point2D"/>
                </item>
            </array>
        </item>
        <item name="pose" desc="Position and orientation of the shape">
            <data_format_ref name="Transform3D"/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Shape3D.Polygon",
  "data" : {
    "points" : [ {
      "x" : 1.0,
      "y" : 2.0
    }, {
      "x" : 4.0,
      "y" : 5.0
    } ],
    "pose" : {
      "Type" : "TRANSLATION",
      "Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
    }
  }
}

Shape3D.Polyline

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="points">
            <array>
                <item>
                    <data_format_ref name="Point3D"/>
                </item>
            </array>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Shape3D.Polyline",
  "data" : {
    "points" : [ {
      "x" : 1.0,
      "y" : 2.0,
      "z" : 3.0
    }, {
      "x" : 4.0,
      "y" : 5.0,
      "z" : 6.0
    } ]
  }
}

Shape3D.Rectangle

Directly referenced data formats

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="sizeX" desc="Total extent of the rectangle along its local x-direction">
            <float width="64"/>
        </item>
        <item name="sizeY" desc="Total extent of the rectangle along its local y-direction">
            <float width="64"/>
        </item>
        <item name="pose" desc="Position and orientation of the shape">
            <data_format_ref name="Transform3D"/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Shape3D.Rectangle",
  "data" : {
    "sizeX" : 10,
    "sizeY" : 4,
    "pose" : {
      "Type" : "TRANSLATION",
      "Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
    }
  }
}

Shape3D.Sphere

Directly referenced data formats

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="radius" desc="Radius of the sphere">
            <float width="64"/>
        </item>
        <item name="pose" desc="Position and orientation of the shape">
            <data_format_ref name="Transform3D"/>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Shape3D.Sphere",
  "data" : {
    "radius" : 10,
    "pose" : {
      "Type" : "TRANSLATION",
      "Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
    }
  }
}

Transform

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <polymorphic>
        <data_format_ref name="Transform2D"/>
        <data_format_ref name="Transform3D"/>
    </polymorphic>
</item>

Sample

{
  "class" : "Transform2D",
  "data" : {
    "Type" : "IDENTITY",
    "Matrix" : [ [ 1, 0, 0 ], [ 0, 1, 0 ], [ 0, 0, 1 ] ]
  }
}

Transform2D

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Type">
            <any_of>
                <item>
                    <string value="IDENTITY"/>
                </item>
                <item>
                    <string value="TRANSLATION"/>
                </item>
                <item>
                    <string value="RIGID"/>
                </item>
                <item>
                    <string value="SIMILARITY"/>
                </item>
                <item>
                    <string value="AFFINE"/>
                </item>
                <item>
                    <string value="HOMOGRAPHY"/>
                </item>
            </any_of>
        </item>
        <item name="Matrix">
            <array>
                <item>
                    <array>
                        <item>
                            <float width="64"/>
                        </item>
                    </array>
                </item>
            </array>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Transform2D",
  "data" : {
    "Type" : "IDENTITY",
    "Matrix" : [ [ 1, 0, 0 ], [ 0, 1, 0 ], [ 0, 0, 1 ] ]
  }
}

Transform3D

Specification

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Type">
            <any_of>
                <item>
                    <string value="IDENTITY"/>
                </item>
                <item>
                    <string value="TRANSLATION"/>
                </item>
                <item>
                    <string value="RIGID"/>
                </item>
                <item>
                    <string value="SIMILARITY"/>
                </item>
                <item>
                    <string value="AFFINE"/>
                </item>
                <item>
                    <string value="HOMOGRAPHY"/>
                </item>
            </any_of>
        </item>
        <item name="Matrix">
            <array>
                <item>
                    <array>
                        <item>
                            <float width="64"/>
                        </item>
                    </array>
                </item>
            </array>
        </item>
    </struct>
</item>

Sample

{
  "class" : "Transform3D",
  "data" : {
    "Type" : "IDENTITY",
    "Matrix" : [ [ 1, 0, 0, 0 ], [ 0, 1, 0, 0 ], [ 0, 0, 1, 0 ], [ 0, 0, 0, 1 ] ]
  }
}

View.Camera

Directly referenced data formats